code-context-control 2.126.1__tar.gz → 2.127.0__tar.gz

{code_context_control-2.126.1 → code_context_control-2.127.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.126.1
+Version: 2.127.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.126.1 → code_context_control-2.127.0}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.126.1"
+__version__ = "2.127.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -6968,8 +6968,10 @@ def cmd_override(args):
     """
     sub = getattr(args, "override_cmd", None)
     if not sub:
-        print("Usage: c3 override <policy|grant|list|revoke|check|sweep> ...")
+        print("Usage: c3 override <policy|grant|list|revoke|check|sweep|"
+              "requests|approve|deny|costs> ...")
         print("       c3 override policy    # what is escalatable right now")
+        print("       c3 override costs     # which rules keep holding the agent")
         return
 
     from services import override_grants as og
@@ -6998,6 +7000,39 @@ def cmd_override(args):
         _override_requests(args, project_path)
     elif sub in ("approve", "deny"):
         _override_decide(args, sub, project_path)
+    elif sub == "costs":
+        _override_costs(args, project_path)
+
+
+def _override_costs(args, project_path: str) -> None:
+    """`c3 override costs` — which rules keep holding the agent (§11 T5)."""
+    from services import override_costs as ocost
+
+    days = max(1, int(getattr(args, "days", None) or ocost.DEFAULT_DAYS))
+    everywhere = bool(getattr(args, "all_projects", False))
+    rows = ocost.rule_costs(project_path=None if everywhere else project_path,
+                            days=days)
+    print_header(f"Override costs — last {days} day(s)"
+                 + ("" if everywhere else f" · {Path(project_path).name}"))
+    if not rows:
+        print("  (no requests in the window)")
+        return
+    width = max(len(r["rule"]) for r in rows)
+    print(f"  {'held':>4} {'ok':>3} {'no':>3} {'exp':>3} {'wait':>4}  "
+          f"{'rule':<{width}}  suggestion")
+    for r in rows:
+        line = (f"  {r['count']:>4} {r['approved']:>3} {r['denied']:>3} "
+                f"{r['expired']:>3} {r['pending']:>4}  {r['rule']:<{width}}  "
+                f"{r['suggestion']}")
+        if r["count"] >= ocost.NUDGE_THRESHOLD:
+            line += "  <- costing you"
+        print(line)
+        if everywhere:
+            print(f"  {'':22s} {r['project_path']}")
+    print("\n  held = requests filed; ok/no/exp/wait = approved/denied/"
+          "expired/still pending (withdrawn counts in held only).")
+    print("  A rule you keep approving is friction: edit it with `c3 access`. "
+          "A rule you keep denying is working — mute the session instead.")
 
 
 def _override_requests(args, project_path: str) -> None:

{code_context_control-2.126.1 → code_context_control-2.127.0}/cli/commands/parser.py

@@ -779,6 +779,18 @@ def build_parser(version: str, parse_cli_ide_arg):
     ov_deny.add_argument("--path", dest="project_path", default=".",
                          help="Project directory (default: current)")
 
+    # Costs: which rules keep asking (spec §11 Threat 5, v2.127.0). A read
+    # over the request store — it decides nothing and edits no rule.
+    ov_costs = override_subs.add_parser(
+        "costs", help="Which rules held the agent most, and how you answered"
+    )
+    ov_costs.add_argument("--days", type=int, default=7,
+                          help="Trailing window in days (default 7)")
+    ov_costs.add_argument("--all", dest="all_projects", action="store_true",
+                          help="Every project, not just this one")
+    ov_costs.add_argument("--path", dest="project_path", default=".",
+                          help="Project directory (default: current)")
+
     # ── Tool discipline / enforcement mode (v2.66.0) ────────────────────
     # LAYER C: how hard C3 pushes the agent toward c3_* tools. Distinct from
     # `c3 access` (path policy — a security boundary) and from

{code_context_control-2.126.1 → code_context_control-2.127.0}/cli/hub_server.py

@@ -3215,6 +3215,43 @@ def api_hub_overrides():
                     "limit": limit})
 
 
+@app.route("/api/hub/overrides/costs", methods=["GET"])
+def api_hub_override_costs():
+    """Per-(project, rule) request counts over a trailing window (§11 T5).
+
+    The "this rule is costing you" strip. Query: path (optional — omit for
+    every project in the store; the hub is this machine's own surface and
+    does not filter to a registry), days (1..30, default 7). Response:
+    {days, threshold, rules: [...], count, project} with the row shape of
+    ``services.override_costs.FIELDS``; ``threshold`` is the count at which
+    the UI says something, so the strip and the desktop tray agree on it.
+    Registered before the POST-only ``<request_id>`` route so a GET on
+    ``costs`` can never fall through to a 405 there.
+    """
+    from services import override_costs as ocost
+    project_path = ""
+    raw_project = (request.args.get("path") or "").strip()
+    if raw_project:
+        try:
+            project_path = str(_resolve_project_path(raw_project))
+        except ValueError as e:
+            return jsonify({"error": str(e)}), 404
+    try:
+        days = int(request.args.get("days") or ocost.DEFAULT_DAYS)
+    except (TypeError, ValueError):
+        days = ocost.DEFAULT_DAYS
+    days = max(1, min(ocost.MAX_DAYS, days))
+    try:
+        rules = ocost.rule_costs(project_path=project_path or None, days=days)
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+    for r in rules:
+        r["project_name"] = Path(str(r.get("project_path") or ".")).name
+    return jsonify({"days": days, "threshold": ocost.NUDGE_THRESHOLD,
+                    "rules": rules, "count": len(rules),
+                    "project": project_path})
+
+
 @app.route("/api/hub/overrides/<request_id>", methods=["POST"])
 def api_hub_override_decide(request_id):
     """Approve (minting a grant) or deny one request. decided_by='desktop'.

{code_context_control-2.126.1 → code_context_control-2.127.0}/cli/hub_ui/components/hub_access.js

@@ -185,11 +185,79 @@ function AccRequestCard({ row, busy, onDecide, onTypedApprove, onRuleApprove })
   );
 }
 
+// ── "Costing you" — the §11 Threat 5 nudge ─────────────────────────────────
+// One row per rule that held at least `threshold` times in the window. The
+// count is the argument: a rule the user keeps approving is friction, and a
+// rule they keep denying is doing its job against an agent that will not
+// stop asking. Either way the fix is the RULE, not the next card — so the
+// only affordance is "open the rule", which jumps to it in the policy matrix
+// below. The strip never approves anything and never edits policy; it says
+// the number out loud, which is the mitigation the spec asks for.
+function accSamePath(a, b) {
+  const norm = (p) => String(p || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  return norm(a) === norm(b);
+}
+
+function AccCostStrip({ onOpenRule }) {
+  const [data, setData] = useState(null);
+
+  const load = useCallback(async () => {
+    try {
+      setData(await api.get('/api/hub/overrides/costs?days=7'));
+    } catch { /* keep the last good strip */ }
+  }, []);
+
+  useEffect(() => { load(); }, [load]);
+  usePoll(load, 15000);
+
+  if (!data) return null;
+  const threshold = Number(data.threshold) || 3;
+  const rows = (data.rules || []).filter(r => (Number(r.count) || 0) >= threshold);
+  if (rows.length === 0) return null;
+  return (
+    <div style={{
+      background: T.surface, border: `1px solid ${T.warn}`, borderRadius: 10,
+      padding: '10px 14px',
+    }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap', marginBottom: 4 }}>
+        <span style={{ fontSize: 12.5, fontWeight: 700, color: T.warn }}>Costing you</span>
+        <span style={{ fontSize: 11, color: T.textDim }}>
+          rules that held {threshold}+ times in the last {data.days} days — fix the
+          rule, not the next card
+        </span>
+      </div>
+      {rows.map(r => (
+        <div key={`${r.project_path}|${r.rule}`} style={{
+          display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap',
+          padding: '4px 0', fontSize: 11.5, color: T.textMuted,
+        }}>
+          <span className="mono" title={r.project_path} style={{
+            fontSize: 10.5, padding: '2px 7px', borderRadius: 4,
+            background: T.surfaceAlt, color: T.textMuted,
+          }}>{r.project_name || r.project_path}</span>
+          <span>
+            <b className="mono" style={{ color: T.text }}>{r.rule}</b>
+            {' '}held {r.count}× this week ({r.approved} approved) — {r.suggestion}
+          </span>
+          <div style={{ flex: 1 }} />
+          <Btn variant="ghost" onClick={() => onOpenRule(r)}
+            style={{ padding: '4px 10px' }}>Open rule</Btn>
+        </div>
+      ))}
+    </div>
+  );
+}
+
 // ── Read-only per-project policy matrix ────────────────────────────────────
-function AccRulesPanel({ projects }) {
+// `focus` ({path, rule, seq}) comes from the cost strip's "Open rule": the
+// panel switches to that project, scrolls itself into view and outlines the
+// chip whose glob is the rule. A synthetic rule (discipline / shell) has no
+// chip, so the scroll alone is the answer there.
+function AccRulesPanel({ projects, focus }) {
   const [path, setPath] = useState('');
   const [data, setData] = useState(null);
   const [err, setErr] = useState('');
+  const panelRef = useRef(null);
 
   const load = useCallback(async (p) => {
     if (!p) { setData(null); setErr(''); return; }
@@ -199,10 +267,28 @@ function AccRulesPanel({ projects }) {
     } catch (e) { setData(null); setErr(apiErr(e)); }
   }, []);
 
+  // Deliberately keyed on `focus` alone: `projects` is rebuilt by the hub's
+  // own poll, and re-running this on every poll would re-scroll the page
+  // under the user every few seconds.
+  useEffect(() => {
+    if (!focus || !focus.path) return;
+    // Prefer the hub's own spelling of the project so the <select> shows it;
+    // the store's spelling still loads when the project is not registered.
+    const known = (projects || []).find(p => accSamePath(p.path, focus.path));
+    const target = known ? known.path : focus.path;
+    setPath(target);
+    load(target);
+    const el = panelRef.current;
+    if (el && typeof el.scrollIntoView === 'function') {
+      el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+  }, [focus]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const hot = focus && focus.rule ? String(focus.rule) : '';
   const scopes = (data && data.rules) || {};
   const layerRows = data && data.policy ? Object.entries(data.policy.layers || {}) : [];
   return (
-    <div style={{
+    <div ref={panelRef} style={{
       background: T.surface, border: `1px solid ${T.border}`, borderRadius: 10,
       padding: '12px 16px',
     }}>
@@ -249,14 +335,21 @@ function AccRulesPanel({ projects }) {
                   <div style={{ fontSize: 11.5, color: T.textDim }}>no rules</div>
                 ) : (
                   <div style={{ display: 'flex', flexWrap: 'wrap', gap: 6 }}>
-                    {rows.map(([kind, glob], i) => (
-                      <span key={i} className="mono" style={{
-                        fontSize: 11, padding: '2px 8px', borderRadius: 4,
-                        color: ACC_KIND_COLOR(kind),
-                        background: `${ACC_KIND_COLOR(kind)}18`,
-                        border: `1px solid ${ACC_KIND_COLOR(kind)}44`,
-                      }} title={kind}>{kind}: {glob}</span>
-                    ))}
+                    {rows.map(([kind, glob], i) => {
+                      const lit = hot && glob === hot;
+                      return (
+                        <span key={i} className="mono" style={{
+                          fontSize: 11, padding: '2px 8px', borderRadius: 4,
+                          color: ACC_KIND_COLOR(kind),
+                          background: `${ACC_KIND_COLOR(kind)}18`,
+                          border: `1px solid ${ACC_KIND_COLOR(kind)}44`,
+                          outline: lit ? `2px solid ${T.warn}` : 'none',
+                          outlineOffset: lit ? 2 : 0,
+                        }} title={lit ? `${kind} — this rule is costing you` : kind}>
+                          {kind}: {glob}
+                        </span>
+                      );
+                    })}
                   </div>
                 )}
                 {scope === 'builtin' && (sec.disabled || []).length > 0 && (
@@ -395,6 +488,11 @@ function HubAccess({ projects }) {
   const [chip, setChip] = useState('pending');
   const [busyId, setBusyId] = useState('');
   const [confirmSpec, setConfirmSpec] = useState(null);
+  // `seq` makes a second click on the same rule re-fire the panel's effect.
+  const [ruleFocus, setRuleFocus] = useState(null);
+  const openRule = (r) => setRuleFocus({
+    path: r.project_path, rule: r.rule, seq: Date.now(),
+  });
 
   const load = useCallback(async () => {
     try {
@@ -459,6 +557,8 @@ function HubAccess({ projects }) {
         ))}
       </div>
 
+      <AccCostStrip onOpenRule={openRule} />
+
       {!loaded ? (
         <div style={{ fontSize: 12, color: T.textDim }}>Loading…</div>
       ) : rows.length === 0 ? (
@@ -479,7 +579,7 @@ function HubAccess({ projects }) {
       )}
 
       <AccGrantsPanel projects={projects} />
-      <AccRulesPanel projects={projects} />
+      <AccRulesPanel projects={projects} focus={ruleFocus} />
       {confirmSpec && (
         <CredConfirm spec={confirmSpec} onClose={() => setConfirmSpec(null)} />
       )}

{code_context_control-2.126.1 → code_context_control-2.127.0}/code_context_control.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.126.1
+Version: 2.127.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.126.1 → code_context_control-2.127.0}/code_context_control.egg-info/SOURCES.txt

@@ -260,6 +260,7 @@ services/ollama_client.py
 services/ollama_credentials.py
 services/oracle_service.py
 services/output_filter.py
+services/override_costs.py
 services/override_grants.py
 services/override_policy.py
 services/override_requests.py
@@ -419,6 +420,7 @@ tests/test_mobile_api.py
 tests/test_mobile_clients.py
 tests/test_mobile_extras.py
 tests/test_mobile_jobs_ci.py
+tests/test_mobile_override_costs.py
 tests/test_mobile_override_routes.py
 tests/test_mobile_security_api.py
 tests/test_no_stale_model_pins.py
@@ -443,6 +445,7 @@ tests/test_oracle_session_bootstrap.py
 tests/test_oracle_subproject_awareness.py
 tests/test_oracle_ui_bundle.py
 tests/test_output_filter.py
+tests/test_override_costs.py
 tests/test_override_grants.py
 tests/test_override_grants_mcp.py
 tests/test_override_requests.py

{code_context_control-2.126.1 → code_context_control-2.127.0}/oracle/services/mobile_api.py

@@ -71,6 +71,11 @@ from services.atomic_json import write_json_atomic
 #    reports the caller as `client: {kind, client_id}`, and override
 #    decisions are attributed to that kind ("desk" for the tray client,
 #    "mobile" for a phone or the legacy Discovery token).
+# 5 (unchanged, additive, v2.127.0): `override_costs` capability and
+#    GET /overrides/costs — per-(project, rule) request counts over a
+#    trailing window, the "this rule is costing you" nudge (D3a). The
+#    /overrides/<id> detail also carries `allow_session_grants`,
+#    `max_ttl_s` and `session_confirm` at the top level.
 API_VERSION = 5
 
 CAPABILITIES = [
@@ -79,7 +84,7 @@ CAPABILITIES = [
     "credentials", "credentials_write",
     "access", "access_write",
     "enforcement", "enforcement_write",
-    "override", "override_write",
+    "override", "override_write", "override_costs",
     "edits", "locks", "status",
     "insights", "insights_write",
     "suggestions", "suggestions_write",
@@ -103,6 +108,9 @@ _CAPABILITY_SWITCHES = {
     "enforcement_write": "mobile_access_write",
     "override": "mobile_override_enabled",
     "override_write": "mobile_override_write",
+    # The cost view is a read over the same store the inbox serves, so it
+    # goes dark with the inbox rather than carrying a switch of its own.
+    "override_costs": "mobile_override_enabled",
     # The ops reads (edits, locks, status, insights, suggestions, review) are
     # deliberately absent: they expose nothing the feed does not already, so
     # gating them would only cost a client a capability probe. Only the two
@@ -2439,6 +2447,60 @@ def _write_override_section(project: Path, section: dict) -> dict:
     return block
 
 
+def _days_arg(default: int, ceiling: int) -> int:
+    """``?days=`` clamped to ``[1, ceiling]``; garbage reads as the default.
+
+    A clamp rather than a 400 because the value only sizes a window — a
+    client asking for a quarter gets the month it is allowed, and the answer
+    echoes the window actually used so it can say so.
+    """
+    try:
+        want = int(request.args.get("days", default))
+    except (TypeError, ValueError):
+        want = default
+    return max(1, min(ceiling, want))
+
+
+@bp.route("/overrides/costs", methods=["GET"])
+def mobile_overrides_costs():
+    """Per-(project, rule) request counts over a trailing window (§11 T5).
+
+    The "this rule is costing you" number. Query: project (optional — omit
+    for every project this gateway serves), days (1..30, default 7).
+    Response: {days, rules: [{project_path, rule, rule_class, layer, count,
+    approved, denied, expired, pending, last_at, suggestion}], count,
+    project}. Rows sort by count desc then last_at desc; the desktop shows
+    `suggestion` verbatim and nudges at count >= 3.
+
+    Registered BEFORE `/overrides/<id>` for the same reason `policy` is: the
+    ordering is explicit so `costs` can never become a request id.
+    """
+    gate = _feature_or_404("override_costs")
+    if gate:
+        return gate
+    from services import override_costs as ocost
+    raw_project = (request.args.get("project") or "").strip()
+    project_path = ""
+    if raw_project:
+        resolved, err = _project_or_404(raw_project)
+        if err:
+            return err
+        project_path = str(resolved)
+    days = _days_arg(ocost.DEFAULT_DAYS, ocost.MAX_DAYS)
+    try:
+        rules = ocost.rule_costs(project_path=project_path or None, days=days)
+    except Exception as exc:
+        return _svc_error(exc)
+    if not project_path:
+        # Same rule as /overrides and /jobs: the store is one file for the
+        # whole machine, and a cross-project view must not name a project
+        # this token cannot otherwise see.
+        rules = [r for r in rules
+                 if _resolve_registered(str(r.get("project_path") or "")) is not None]
+    return jsonify({"days": days, "rules": rules, "count": len(rules),
+                    "project": project_path})
+
+
 @bp.route("/overrides/<request_id>", methods=["GET"])
 def mobile_override_get(request_id):
     """One request, full context."""
@@ -2481,6 +2543,15 @@ def mobile_override_get(request_id):
         "confirm_with": (
             row.get("rule") if str(row.get("rule_class") or "")
             in opol.TYPED_CONFIRM_LAYERS else ""),
+        # Top-level as well as under `policy` (v2.127.0): what a session-grant
+        # button needs, in one fetch — whether the switch is on, how long the
+        # grant would last, and the literal the client must send as
+        # `confirm` (`decide()` demands it on the layers that are otherwise
+        # one-tap). Duplicated on purpose: a client should not need the
+        # policy dict's shape to draw one button.
+        "allow_session_grants": bool(policy.allow_session_grants),
+        "max_ttl_s": int(policy.max_ttl_s),
+        "session_confirm": orq.CONFIRM_SESSION,
     })
 
 

{code_context_control-2.126.1 → code_context_control-2.127.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.126.1"
+version = "2.127.0"
 description = "Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub."
 readme = "README.md"
 requires-python = ">=3.10"

code_context_control-2.127.0/services/override_costs.py

@@ -0,0 +1,183 @@
+"""Override costs — the "this rule is costing you" nudge (spec §11 Threat 5).
+
+The request store answers "what is waiting?"; nothing answered "which rule
+keeps asking?". On 2026-09-06 one session filed six holds on
+``**/.claude/skills/**`` for ONE file in 65 minutes — four approved by hand,
+two lost to the TTL — and every surface rendered each card as if it were the
+first. Approval fatigue is the threat §11 calls "the real one", and its
+mitigation is a number: how often a rule held, and how the human answered.
+
+This module is that number. It is a READ-ONLY fold over
+``~/.c3/oracle/override_requests.json`` grouped by ``(project_path, rule)``
+over a trailing window — never a decision, never a mutation, not even the
+store's own lazy expiry flip (a lapsed pending row is *counted* as expired
+against the supplied clock; flipping it on disk stays with the readers that
+already do so). A corrupt or missing store reads as no rows, which is the
+honest answer for a nudge: silence, not a crash in a route or a tray.
+
+Consumers: ``GET /api/mobile/overrides/costs`` (desktop tray nudge),
+``GET /api/hub/overrides/costs`` (Hub "Costing you" strip),
+``c3 override costs``. The desktop shows ``suggestion`` verbatim, so its
+three values are part of the wire contract.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from services import override_grants as og
+from services import override_requests as orq
+
+#: Window defaults. ``MAX_DAYS`` is the remote ceiling (the gateway clamps
+#: to it); the CLI may ask for more, because a person at the keyboard asking
+#: for a quarter's history is not a phone hammering the store.
+DEFAULT_DAYS = 7
+MAX_DAYS = 30
+
+#: How many holds per rule per window before a surface should say something.
+#: Shared by the desktop client (hard-coded there to the same value) and the
+#: Hub strip; a rule that held twice is a coincidence, three times is a cost.
+NUDGE_THRESHOLD = 3
+
+#: The one-line verdicts. The desktop renders them verbatim — change the
+#: wording here and the tray changes with it, so treat them as contract.
+SUGGEST_ALLOW = "convert to allow"
+SUGGEST_TIGHTEN = "tighten or deny"
+SUGGEST_REVIEW = "review"
+
+#: Output row shape, in order. ``count`` is EVERY request in the window
+#: (withdrawn included); the four buckets are the human-visible outcomes and
+#: deliberately leave ``withdrawn`` out — the agent cancelling its own
+#: question says nothing about whether the rule costs the user anything.
+FIELDS = (
+    "project_path", "rule", "rule_class", "layer",
+    "count", "approved", "denied", "expired", "pending",
+    "last_at", "suggestion",
+)
+
+
+def suggestion(approved: int, denied: int) -> str:
+    """The verdict for one rule's window.
+
+    ``convert to allow`` — the user keeps saying yes and has never said no;
+    the rule is friction, not protection, for this project. ``tighten or
+    deny`` — the user has said no at least twice; the rule is doing its job
+    and the agent should stop asking, or the rule should be narrower so the
+    legitimate case stops tripping it. Anything else is ``review``.
+    """
+    if denied >= 2:
+        return SUGGEST_TIGHTEN
+    if approved >= 3 and denied == 0:
+        return SUGGEST_ALLOW
+    return SUGGEST_REVIEW
+
+
+def _effective_status(row: dict, at: datetime) -> str:
+    """A pending row past its ``expires_at`` IS expired, whether or not a
+    writer has flipped it yet. Evaluated against the caller's clock so a
+    fixed ``now`` in a test sees the same answer the live store would."""
+    status = str(row.get("status") or "")
+    if status == orq.STATUS_PENDING:
+        exp = og.parse_ts(row.get("expires_at"))
+        if exp is None or at >= exp:
+            return orq.STATUS_EXPIRED
+    return status
+
+
+def _project_key(raw: str, cache: dict) -> str:
+    """Grouping identity for a project path — same canonicaliser
+    ``list_requests`` filters with, so a row spelled ``Y:/Projects/X`` and a
+    filter spelled ``y:\\projects\\x`` land in one group. Empty stays empty:
+    ``path_key('')`` would resolve to the CWD and silently adopt orphan rows."""
+    raw = str(raw or "")
+    if not raw:
+        return ""
+    if raw not in cache:
+        try:
+            cache[raw] = og.path_key(raw) or raw.replace("\\", "/").lower()
+        except Exception:
+            cache[raw] = raw.replace("\\", "/").lower()
+    return cache[raw]
+
+
+def _load_rows() -> list:
+    """Every request row, or ``[]`` — a nudge must never raise."""
+    try:
+        rows = orq.load()
+    except Exception:
+        return []
+    return [r for r in rows if isinstance(r, dict)]
+
+
+def rule_costs(project_path: str | None = None, days: int = DEFAULT_DAYS,
+               now: datetime | None = None) -> list:
+    """Per-``(project_path, rule)`` request counts over the trailing window.
+
+    ``project_path`` narrows to one project (any spelling); ``None`` / ``""``
+    means every project in the store — callers serving a token MUST filter
+    the result to what that token may see (the store is one file for the
+    whole machine). ``days`` is the window length in days, floor 1; the
+    window is ``[now - days, now]`` on ``created_at``. ``now`` defaults to
+    the wall clock.
+
+    Returns a list of dicts with exactly :data:`FIELDS`, sorted by ``count``
+    descending then ``last_at`` descending. Never raises on store trouble.
+    """
+    at = now or og.now()
+    try:
+        span = max(1, int(days))
+    except (TypeError, ValueError):
+        span = DEFAULT_DAYS
+    since = at - timedelta(days=span)
+
+    cache: dict = {}
+    want = _project_key(project_path or "", cache) if project_path else ""
+
+    groups: dict = {}
+    for row in _load_rows():
+        created = og.parse_ts(row.get("created_at"))
+        if created is None or created < since or created > at:
+            continue
+        proj_key = _project_key(row.get("project_path", ""), cache)
+        if want and proj_key != want:
+            continue
+        rule = str(row.get("rule") or "")
+        key = (proj_key, rule)
+        grp = groups.get(key)
+        if grp is None:
+            grp = groups[key] = {
+                "project_path": str(row.get("project_path") or ""),
+                "rule": rule,
+                "rule_class": str(row.get("rule_class") or ""),
+                "layer": str(row.get("layer") or ""),
+                "count": 0, "approved": 0, "denied": 0,
+                "expired": 0, "pending": 0,
+                "last_at": "", "_last_dt": None,
+            }
+        grp["count"] += 1
+        status = _effective_status(row, at)
+        if status in ("approved", "denied", "expired", "pending"):
+            grp[status] += 1
+        if grp["_last_dt"] is None or created > grp["_last_dt"]:
+            grp["_last_dt"] = created
+            grp["last_at"] = str(row.get("created_at") or "")
+            # The newest row is the most honest source for the labels — a
+            # rule reclassified mid-window reports what it is NOW.
+            grp["rule_class"] = str(row.get("rule_class") or grp["rule_class"])
+            grp["layer"] = str(row.get("layer") or grp["layer"])
+            grp["project_path"] = str(row.get("project_path") or grp["project_path"])
+
+    out = []
+    for grp in groups.values():
+        grp["suggestion"] = suggestion(grp["approved"], grp["denied"])
+        out.append(grp)
+    # count desc, then most recent first. Every group has a `_last_dt` (the
+    # first row that opened it set one), so the fallback never fires; it is
+    # there so a sort key can never be None.
+    out.sort(key=lambda g: (-g["count"],
+                            -(g["_last_dt"] or since).timestamp()))
+    return [{k: grp[k] for k in FIELDS} for grp in out]
+
+
+def costing(rules: list, threshold: int = NUDGE_THRESHOLD) -> list:
+    """The subset a surface should actually nudge about."""
+    return [r for r in rules if int(r.get("count") or 0) >= threshold]