swarph-cli 0.72.28__tar.gz → 0.72.30__tar.gz

{swarph_cli-0.72.28/src/swarph_cli.egg-info → swarph_cli-0.72.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.72.28
+Version: 0.72.30
 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
@@ -179,7 +179,7 @@ The mesh **board** — the projects + cards kanban the mesh coordinates on — a
 ```
 swarph board projects list
 swarph board projects add <slug> --title "…" [--goal "…"]
-swarph board cards list [--project <id|slug>] [--stage <s>] [--assignee <who>]
+swarph board cards list [--project <id|slug>] [--stage <s>] [--assignee <who>] [--search <text>]   # --search: title OR body, says how many cards it searched
 swarph board cards show <id>
 swarph board cards add --project <id|slug> --title "…" [--body "…"] [--ai2] [--priority N]
 swarph board cards edit <id> [--title "…"] [--body "…"] [--project <id|slug>] [--priority N]

{swarph_cli-0.72.28 → swarph_cli-0.72.30}/README.md

@@ -130,7 +130,7 @@ The mesh **board** — the projects + cards kanban the mesh coordinates on — a
 ```
 swarph board projects list
 swarph board projects add <slug> --title "…" [--goal "…"]
-swarph board cards list [--project <id|slug>] [--stage <s>] [--assignee <who>]
+swarph board cards list [--project <id|slug>] [--stage <s>] [--assignee <who>] [--search <text>]   # --search: title OR body, says how many cards it searched
 swarph board cards show <id>
 swarph board cards add --project <id|slug> --title "…" [--body "…"] [--ai2] [--priority N]
 swarph board cards edit <id> [--title "…"] [--body "…"] [--project <id|slug>] [--priority N]

{swarph_cli-0.72.28 → swarph_cli-0.72.30}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.72.28"
+version = "0.72.30"
 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" }
@@ -173,3 +173,6 @@ testpaths = ["tests"]
 # nearly identical. That agreement is a polluted baseline, not isolation.
 pythonpath = ["src"]
 addopts = "-v --tb=short"
+markers = [
+    "live_tmux: drives a real tmux server/pane; opt-in, and the test must state its reason (card #1034)",
+]

{swarph_cli-0.72.28 → swarph_cli-0.72.30}/src/swarph_cli/__init__.py

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

{swarph_cli-0.72.28 → swarph_cli-0.72.30}/src/swarph_cli/bench/claude_cli.py

@@ -23,9 +23,12 @@ class CliResult:
 
 
 def build_argv(model_id: str, system: str) -> list:
+    # Card #1090: one token each. --mcp-config is variadic, so a following
+    # JSON token is consumed only while the token after that is a flag.
     return ["claude", "-p", "--model", model_id, "--system-prompt", system, "--max-turns", "1",
-            "--output-format", "stream-json", "--verbose", "--strict-mcp-config",
-            "--mcp-config", '{"mcpServers":{}}', "--tools", "", "--setting-sources", ""]
+            "--output-format", "stream-json", "--verbose",
+            "--tools=", "--strict-mcp-config",
+            '--mcp-config={"mcpServers":{}}', "--setting-sources="]
 
 
 def clean_env(env: dict) -> dict:

swarph_cli-0.72.30/src/swarph_cli/bench/prices.py

@@ -0,0 +1,284 @@
+"""The auto-refreshed LLM LIST-price table (spec §4) — LIFTED from the
+reference lab's already-tested ``workers/llm_prices.py`` (adapted imports/
+cache path only; lookup semantics, fallback table, and substring-order bug
+guard are unchanged). Do NOT reinvent this — see
+``docs/2026-07-24-model-showdown-findings.md`` shipped-alongside note: it
+already caught a real ~5x under-count on gemini-2.5-flash-lite.
+
+The LIST-price BASE is auto-refreshed from the community-maintained LiteLLM
+repo (:mod:`swarph_cli.bench.refresh_prices` -> a local JSON cache; TODO wire
+a weekly cron the way the reference lab does), so new models are never
+silently mis-priced by a stale hardcoded bucket.
+
+Public API:
+    lookup(model) -> (input_$/Mtok, output_$/Mtok)   # never raises
+    cost_usd(model, tokens_in, tokens_thought, tokens_out) -> $
+"""
+from __future__ import annotations
+
+import datetime
+import json
+import logging
+import os
+import tempfile
+
+log = logging.getLogger("swarph.bench.prices")
+
+# card #1250. A cache older than this is refreshed on load(). Exactly this
+# age is still fresh: "older than", not "at least".
+PRICE_CACHE_TTL_S = 7 * 24 * 60 * 60
+# Both load()-triggered fetches. refresh_prices.main() keeps its own 30s.
+LOAD_FETCH_TIMEOUT_S = 5
+
+
+def _default_cache_path() -> str:
+    """User cache, never the installed package.
+
+    card #1248: a table written next to this file lands in site-packages and
+    goes stale in the wheel. The cache lives under XDG_CACHE_HOME (or
+    ~/.cache). SWARPH_BENCH_PRICE_CACHE overrides it.
+    """
+    override = os.environ.get("SWARPH_BENCH_PRICE_CACHE")
+    if override:
+        return override
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(
+        os.path.expanduser("~"), ".cache")
+    return os.path.join(base, "swarph", "llm_prices.json")
+
+
+_CACHE_PATH = _default_cache_path()
+_MAP: dict | None = None
+# lookup() warns once per model per process when a loaded table has no row.
+_FALLBACK_WARNED: set[str] = set()
+
+# Reconciled fallbacks ($/Mtok input, output) — used ONLY when a model isn't in
+# the refreshed cache. The cache is the real source; these are the safety net.
+_FALLBACK = {
+    "pro": (1.25, 10.0),
+    "lite": (0.019, 0.075),
+    "flash": (0.30, 2.50),
+}
+
+
+def _now() -> datetime.datetime:
+    return datetime.datetime.now(datetime.timezone.utc)
+
+
+def _read_payload() -> dict | None:
+    try:
+        with open(_CACHE_PATH) as f:
+            data = json.load(f) or {}
+        return data if isinstance(data, dict) else None
+    except Exception:
+        return None
+
+
+def _prices_of(payload: dict | None) -> dict:
+    if not payload:
+        return {}
+    prices = payload.get("prices")
+    return prices if isinstance(prices, dict) else {}
+
+
+def _generated_at(payload: dict | None) -> datetime.datetime | None:
+    """UTC timestamp, or None when the field is missing or unparseable."""
+    if not payload:
+        return None
+    raw = payload.get("generated_at")
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    try:
+        parsed = datetime.datetime.fromisoformat(raw.strip())
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=datetime.timezone.utc)
+    return parsed
+
+
+def _age_days_label(generated: datetime.datetime | None) -> str:
+    if generated is None:
+        return "unknown"
+    return str(max(0, int((_now() - generated).total_seconds() // 86400)))
+
+
+def _read_cache() -> dict:
+    return _prices_of(_read_payload())
+
+
+def _write_cache(prices: dict) -> None:
+    """Atomic write of the user cache. Never writes inside this package."""
+    dest = os.path.abspath(_CACHE_PATH)
+    pkg = os.path.dirname(os.path.abspath(__file__))
+    if dest == pkg or dest.startswith(pkg + os.sep):
+        log.warning(
+            "refusing to write the price table into the package tree (%s)", dest)
+        return
+    payload = {
+        "generated_at": _now().isoformat(),
+        "source": "BerriAI/litellm model_prices_and_context_window.json",
+        "count": len(prices),
+        "prices": prices,
+    }
+    try:
+        os.makedirs(os.path.dirname(dest), exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=os.path.dirname(dest), suffix=".tmp")
+        with os.fdopen(fd, "w") as f:
+            json.dump(payload, f)
+        os.replace(tmp, dest)
+    except OSError as e:
+        log.warning("llm price cache not written (%s)", e)
+
+
+def _fetch_into_cache() -> dict:
+    """Fill the user cache from the price source. Never writes inside
+    this package (that path is site-packages once the wheel is installed).
+
+    This is the empty-cache path. A stale cache goes through
+    ``refresh_prices.guard`` in ``load()`` before it is written.
+    """
+    try:
+        from .refresh_prices import fetch
+        fresh = fetch(timeout=LOAD_FETCH_TIMEOUT_S)
+    except Exception as e:
+        log.warning("llm price fetch failed (%s)", e)
+        return {}
+    if not fresh:
+        return {}
+    _write_cache(fresh)
+    return fresh
+
+
+def _keep_stale(prior: dict, generated: datetime.datetime | None) -> dict:
+    log.warning(
+        "llm price refresh failed — keeping the stale table, %s days old",
+        _age_days_label(generated),
+    )
+    return prior
+
+
+def load(force: bool = False) -> dict:
+    """The cached ``{normalized_model: {"in": $/Mtok, "out": $/Mtok}}`` map.
+    Cached in-process; ``force=True`` re-reads. Never raises.
+
+    A missing cache is fetched once into the user cache. If that also fails,
+    the empty table is a WARNING, not a DEBUG line: every later lookup is
+    then a built-in fallback (card #1248).
+
+    A cache older than ``PRICE_CACHE_TTL_S``, or one whose ``generated_at``
+    is missing or unparseable, is refreshed through ``refresh_prices.guard``.
+    A failed refresh keeps the stale table (card #1250).
+    """
+    global _MAP
+    if _MAP is not None and not force:
+        return _MAP
+    payload = _read_payload()
+    prior = _prices_of(payload)
+    generated = _generated_at(payload)
+    if prior and generated is not None:
+        age = (_now() - generated).total_seconds()
+        if age <= PRICE_CACHE_TTL_S:
+            _MAP = prior
+            return _MAP
+    if prior:
+        table = _refresh_stale(prior, generated)
+    else:
+        table = _fetch_into_cache()
+    if not table:
+        log.warning(
+            "llm price table unavailable — pricing from the built-in "
+            "fallbacks (pro/lite/flash). No cache at %s and the price "
+            "source could not be fetched.",
+            _CACHE_PATH,
+        )
+        _MAP = {}
+        return _MAP
+    _MAP = table
+    return _MAP
+
+
+def _refresh_stale(prior: dict, generated: datetime.datetime | None) -> dict:
+    """Refetch a stale table. The guard runs only on this path, and the
+    guarded-count WARNING is logged only here — a first fill has no prior
+    to guard."""
+    try:
+        from .refresh_prices import fetch, guard
+        fresh = fetch(timeout=LOAD_FETCH_TIMEOUT_S)
+    except Exception as e:
+        log.warning("llm price fetch failed (%s)", e)
+        return _keep_stale(prior, generated)
+    if not fresh:
+        return _keep_stale(prior, generated)
+    merged, flagged = guard(fresh, prior)
+    log.warning(
+        "llm price refresh guarded %d change(s) against the stale table",
+        len(flagged),
+    )
+    _write_cache(merged)
+    return merged
+
+
+def _norm(model: str) -> str:
+    """Strip provider prefix (gemini/, vertex_ai/, ...) + lowercase."""
+    return (model or "").split("/")[-1].strip().lower()
+
+
+def lookup(model: str) -> tuple[float, float]:
+    """(input_$/Mtok, output_$/Mtok) for ``model``. Exact cache hit ->
+    substring fallback (lite before flash so 'flash-lite' resolves as lite —
+    order-sensitive, don't reorder). Never raises."""
+    m = _norm(model)
+    prices = load()
+    p = prices.get(m)
+    if p and "in" in p and "out" in p:
+        return (float(p["in"]), float(p["out"]))
+    # substring fallback — ORDER MATTERS: lite is a substring of flash-lite
+    # and must win over flash.
+    if "lite" in m:
+        chosen, label = _FALLBACK["lite"], "lite"
+    elif "pro" in m:
+        chosen, label = _FALLBACK["pro"], "pro"
+    else:
+        chosen, label = _FALLBACK["flash"], "flash"
+    # A loaded table that lacks this model is the #1248 defect class for a
+    # model upstream does not list yet. Once per model per process. An empty
+    # table already warned in load(); don't warn again on every lookup.
+    if prices and m not in _FALLBACK_WARNED:
+        _FALLBACK_WARNED.add(m)
+        log.warning(
+            "llm price for %s is not in the loaded table — using the %s "
+            "fallback %s",
+            m, label, chosen,
+        )
+    return chosen
+
+
+def is_known(model_id: str) -> bool:
+    """True if ``model_id`` has an exact hit in the refreshed cache (as
+    opposed to resolving via the substring fallback)."""
+    p = load().get(_norm(model_id))
+    return bool(p and "in" in p and "out" in p)
+
+
+def cost_usd(model_id: str, tokens_in: int, tokens_thought: int, tokens_out: int) -> float:
+    """Metered $ for one call: in-tokens at the input price, (thought + out)
+    tokens at the output price (mirrors the reference ``metered_usd()``)."""
+    price_in, price_out = lookup(model_id)
+    thought = tokens_thought or 0
+    return (tokens_in * price_in + (thought + tokens_out) * price_out) / 1_000_000
+
+
+def all_cached(force: bool = False) -> dict[str, tuple[float, float]]:
+    """Every ``{model_id: (in, out)}`` currently in the refreshed cache — the
+    full LiteLLM-sourced price list, not just the models ``bench`` happens to
+    price. Exposed so the cache is a reusable mesh asset (e.g. a
+    cost-governor/ledger can read the same cache via ``swarph bench prices``)
+    rather than plumbing private to the runner."""
+    return {m: (float(v["in"]), float(v["out"])) for m, v in load(force=force).items()
+            if isinstance(v, dict) and "in" in v and "out" in v}
+
+
+def fallback_buckets() -> dict[str, tuple[float, float]]:
+    """The 3 built-in substring-fallback buckets (pro/lite/flash), for
+    display when the cache is empty/stale."""
+    return dict(_FALLBACK)

{swarph_cli-0.72.28 → swarph_cli-0.72.30}/src/swarph_cli/bench/refresh_prices.py

@@ -19,6 +19,10 @@ not wired to any scheduler in this PR, just the ported fetch+guard logic.
 
 Network call — never exercised in the offline test suite (mocked or skipped).
 Read-only wrt the rest of swarph-cli: only ever writes the price cache.
+
+``SWARPH_BENCH_PRICE_URL`` overrides the source URL. Only the ``https``,
+``http`` and ``file`` schemes are accepted (card #1250). ``load()`` passes a
+5s timeout; this CLI keeps 30s.
 """
 from __future__ import annotations
 
@@ -26,22 +30,45 @@ import json
 import os
 import sys
 import tempfile
+import urllib.parse
 import urllib.request
 from datetime import datetime, timezone
 
-from .prices import _CACHE_PATH as CACHE_PATH
+def _cache_path() -> str:
+    """Read at call time so a monkeypatch of prices._CACHE_PATH is honored,
+    and so a refresh never keeps an import-time path inside the package."""
+    from .prices import _CACHE_PATH
+    return _CACHE_PATH
 
 LITELLM_URL = ("https://raw.githubusercontent.com/BerriAI/litellm/main/"
                "model_prices_and_context_window.json")
 GUARD_RATIO = 3.0  # reject a new price >3x or <1/3x the prior cached value
+# The CLI's own fetch. load() passes prices.LOAD_FETCH_TIMEOUT_S instead.
+CLI_FETCH_TIMEOUT_S = 30
+_ALLOWED_SOURCE_SCHEMES = frozenset({"https", "http", "file"})
+
+
+def price_source_url() -> str:
+    """The JSON URL ``fetch`` reads.
+
+    ``SWARPH_BENCH_PRICE_URL`` overrides ``LITELLM_URL``. Schemes other than
+    https, http and file are refused.
+    """
+    raw = (os.environ.get("SWARPH_BENCH_PRICE_URL") or LITELLM_URL).strip()
+    scheme = urllib.parse.urlparse(raw).scheme.lower()
+    if scheme not in _ALLOWED_SOURCE_SCHEMES:
+        raise ValueError(
+            f"SWARPH_BENCH_PRICE_URL scheme {scheme!r} is not allowed "
+            "(https, http, file)")
+    return raw
 
 
 def _norm(key: str) -> str:
     return key.split("/")[-1].strip().lower()
 
 
-def fetch() -> dict:
-    raw = urllib.request.urlopen(LITELLM_URL, timeout=30).read()
+def fetch(timeout: float = CLI_FETCH_TIMEOUT_S) -> dict:
+    raw = urllib.request.urlopen(price_source_url(), timeout=timeout).read()
     d = json.loads(raw)
     out: dict[str, dict] = {}
     for key, v in d.items():
@@ -59,7 +86,7 @@ def fetch() -> dict:
 
 def load_prior() -> dict:
     try:
-        with open(CACHE_PATH) as f:
+        with open(_cache_path()) as f:
             return (json.load(f) or {}).get("prices", {}) or {}
     except Exception:
         return {}
@@ -98,11 +125,17 @@ def main() -> int:
     payload = {"generated_at": datetime.now(timezone.utc).isoformat(),
                "source": "BerriAI/litellm model_prices_and_context_window.json",
                "count": len(merged), "prices": merged}
-    os.makedirs(os.path.dirname(CACHE_PATH), exist_ok=True)
-    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(CACHE_PATH), suffix=".tmp")
+    dest = _cache_path()
+    pkg = os.path.dirname(os.path.abspath(os.path.join(os.path.dirname(__file__), "prices.py")))
+    if os.path.abspath(dest).startswith(pkg + os.sep):
+        print(f"refresh_prices: refusing to write into the package tree ({dest})",
+              file=sys.stderr)
+        return 1
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(dest), suffix=".tmp")
     with os.fdopen(fd, "w") as f:
         json.dump(payload, f, indent=2, sort_keys=True)
-    os.replace(tmp, CACHE_PATH)
+    os.replace(tmp, dest)
     print(f"refresh_prices: {len(merged)} models cached "
           f"({len(fresh)} fetched, {len(merged) - len(fresh)} prior-only kept). "
           f"{len(flagged)} guarded.")

{swarph_cli-0.72.28 → swarph_cli-0.72.30}/src/swarph_cli/commands/board.py

@@ -71,9 +71,11 @@ def _patch_json(url: str, body: dict, token: str, *, timeout: float = 10.0) -> t
 # ── pure builders (unit-tested) ───────────────────────────────────────────────
 
 def _cards_list_url(gateway: str, *, project=None, stage=None, assignee=None,
-                    label=None) -> str:
+                    label=None, search=None) -> str:
     q = {k: v for k, v in (("project", project), ("stage", stage),
                            ("assignee", assignee), ("label", label)) if v}
+    if search is not None:  # blank still goes: the gateway refuses it, we do not drop it
+        q["q"] = search
     base = f"{gateway.rstrip('/')}/board/cards"
     return f"{base}?{urllib.parse.urlencode(q)}" if q else base
 
@@ -353,6 +355,10 @@ def _format_due_head(data) -> list[str]:
 def _format_cards(data) -> str:
     head = _format_due_head(data)
     rows = _cards_of(data)
+    if isinstance(data, dict) and "searched" in data:
+        # #931: a zero must say how many cards it looked at.
+        head = [f"searched {data['searched']} cards: {len(rows)} match"] + (
+            [""] + head if head else [])
     if not rows:
         body = ["(no cards)"]
     else:
@@ -604,14 +610,49 @@ def _thread_line(d) -> str:
             f"(#509/#562 — the VERB is the mechanism, the thread is where it lands)")
 
 
+def _hours_token(n) -> str:
+    if isinstance(n, float) and n.is_integer():
+        n = int(n)
+    return str(n)
+
+
+def _clock_line(d) -> str | None:
+    """The due-date clock (#935). It starts when the row is taken, not now.
+
+    `clock_hours` is the menu step's hours, or the `--hours` override.
+    `timeout_at` is a different clock — when the row reads OVERDUE — and
+    is not this line. Absent fields mean an older gateway; the caller
+    keeps its previous sentence rather than inventing a clock.
+    """
+    hours = d.get("clock_hours")
+    if hours is None:
+        return None
+    source = d.get("clock_source") or "menu"
+    menu = d.get("menu_hours")
+    if (source == "override" and isinstance(menu, (int, float))
+            and not isinstance(menu, bool) and menu
+            and isinstance(hours, (int, float)) and not isinstance(hours, bool)):
+        if hours % menu == 0:
+            detail = f"override, {int(hours // menu)}x menu {_hours_token(menu)}h"
+        else:
+            detail = f"override, menu {_hours_token(menu)}h"
+    else:
+        detail = str(source)
+    return f"clock: {_hours_token(hours)}h ({detail}) — STARTS ON TAKE, not now"
+
+
 def _format_ask(d) -> str:
-    """One line naming the obligation, its holder, and when it goes red.
+    """Name the obligation, who owes it, and the deadline clock.
 
     >>> NAMING THE DEADLINE OR ITS ABSENCE IS THE POINT, NOT DECORATION. <<< #145's
     lesson, one layer over: "0 overdue" must not be able to mean "nobody set dates".
-    An obligation with no timeout never goes red on its own, and the operator has to
-    be told that AT THE MOMENT THEY CREATE IT — afterwards it looks identical to one
-    that simply is not late yet.
+    The deadline is the due-date clock (`clock_hours`): the menu step's hours,
+    or the `--hours` override, and it STARTS ON TAKE, not at mint (#935).
+    `timeout_at` is the other clock — when the row READS OVERDUE — and is
+    printed under that name, never as the deadline. A response that carries
+    neither clock says NO TIMEOUT, because an obligation with no timeout never
+    goes red on its own and the operator has to be told that AT THE MOMENT
+    THEY CREATE IT.
 
     #532 applies the same rule to the falsifier: an obligation with no accept
     check reads RED in the sweep, and one whose check has no FAIL branch is
@@ -619,9 +660,17 @@ def _format_ask(d) -> str:
     rows look identical to sound ones.
     """
     when = d.get("timeout_at")
-    deadline = f"overdue after {when}" if when else _NO_TIMEOUT
-    return (f"obligation #{d.get('id')} on card #{d.get('card_id')}: "
-            f"{d.get('holder')} owes it, status={d.get('status')}, {deadline}\n"
+    clock = _clock_line(d)
+    head = (f"obligation #{d.get('id')} on card #{d.get('card_id')}: "
+            f"{d.get('holder')} owes it, status={d.get('status')}")
+    if clock:
+        extra = f"\n  {clock}"
+        extra += f"\n  overdue after {when}" if when else f"\n  {_NO_TIMEOUT}"
+    else:
+        deadline = f"overdue after {when}" if when else _NO_TIMEOUT
+        head = f"{head}, {deadline}"
+        extra = ""
+    return (f"{head}{extra}\n"
             f"  {_accept_line(d.get('accept'))}\n"
             f"  {_thread_line(d)}")
 
@@ -763,6 +812,13 @@ def _ask_line(d) -> str:
         if missing:
             line += f" · still missing: {missing}"
     if not str(state).startswith("closed"):
+        clock = _clock_line(d)
+        if clock:
+            # #935: the due-date clock, then the overdue clock under its own name.
+            # A stepped mint used to say neither, so --timeout-hours was read as the due date.
+            line += "\n  " + clock
+            if d.get("timeout_at"):
+                line += "\n  overdue after " + _s(d["timeout_at"])
         line += "\n  " + _accept_line(d.get("accept"))
         if d.get("step") is None:
             # unstepped: no menu clock, no container — the pre-#591 rules hold
@@ -974,6 +1030,9 @@ def _build_parser() -> argparse.ArgumentParser:
     cl = cards.add_parser("list", help="list cards")
     cl.add_argument("--project"); cl.add_argument("--stage"); cl.add_argument("--assignee")
     cl.add_argument("--label", help="only cards carrying this label (exact match)")
+    cl.add_argument("--search", metavar="TEXT",
+                    help="only cards whose title OR body contains TEXT (case-insensitive, "
+                         "matched by the gateway); prints how many cards were searched")
     cl.add_argument("--json", action="store_true"); _add_common(cl)
     cs = cards.add_parser("show", help="show one card"); cs.add_argument("id", type=int)
     cs.add_argument("--json", action="store_true"); _add_common(cs)
@@ -1034,7 +1093,8 @@ def _build_parser() -> argparse.ArgumentParser:
     ck.add_argument("what", help="what is owed, in one line")
     ck.add_argument("--timeout-hours", type=int, default=None,
                     help="hours until this obligation reads OVERDUE (default: none, "
-                         "which means it never goes red on its own)")
+                         "which means it never goes red on its own). This is not "
+                         "the due-date clock; that is --hours, and it starts on take")
     ck.add_argument("--accept", default=None, metavar='"PASS = ... | FAIL = ..."',
                     help="the falsifiable check that closes this obligation "
                          "(#532). Omitting it mints an obligation that reads RED "
@@ -1057,7 +1117,9 @@ def _build_parser() -> argparse.ArgumentParser:
                     help="explicit edges by step name (added to the menu's); repeatable, "
                          "comma lists and the contract's `+step` spelling all accepted")
     ck.add_argument("--hours", type=int, default=None,
-                    help="clock override, up to 4x the menu value")
+                    help="the due-date clock in hours. Starts on take, not now. "
+                         "Default is the menu step's hours. Up to 4x that value. "
+                         "Not the overdue timeout (--timeout-hours)")
     ck.add_argument("--holder", dest="holder_flag", default=None, metavar="PEER|me",
                     help="who owes it: a peer (offered), `me` (open: a bound self-ask "
                          "is a take), or omit (requested: the eligible set is DM'd)")
@@ -1186,7 +1248,9 @@ def _build_parser() -> argparse.ArgumentParser:
     oa.add_argument("--accept-json", default=None, metavar="'{...}'",
                     help="replace the check with a structured one (#1068); "
                          "mutually exclusive with --accept")
-    oa.add_argument("--hours", type=int, default=None, help="clock override, up to 4x the menu value")
+    oa.add_argument("--hours", type=int, default=None,
+                    help="the due-date clock, starts on take, up to 4x the menu value. "
+                         "Not the overdue timeout")
     oa.add_argument("--needs-add", action="append", dest="needs_add", default=None,
                     metavar="STEP", help="add an edge (repeatable)")
     oa.add_argument("--needs-remove", action="append", dest="needs_remove", default=None,
@@ -1338,7 +1402,15 @@ def run_board(argv: list[str]) -> int:
                 return 1
             st, d = _http_get_json(_cards_list_url(gw, project=pid, stage=args.stage,
                                                    assignee=args.assignee,
-                                                   label=getattr(args, "label", None)), token)
+                                                   label=getattr(args, "label", None),
+                                                   search=args.search), token)
+            if (args.search is not None and st and 200 <= st < 300
+                    and not (isinstance(d, dict) and "searched" in d)):
+                # A gateway older than #931 ignores q and returns EVERY card.
+                print("swarph board: the gateway ignored --search (its reply has no "
+                      "`searched` count), so this list is NOT filtered; refusing to "
+                      "show it as a search result", file=sys.stderr)
+                return 1
             return _out(st, d, _format_cards, aj)
         if args.command == "show":
             st, d = _http_get_json(f"{gw}/board/cards/{args.id}", token)