merge main into feat/miner-metadata-opportunity-ranker

Resolve miner CLI conflicts: foundation status stays top-level; manage portfolio status routes via manage status.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: james3773

grafana/dashboards/gittensory.json

@@ -2786,6 +2786,163 @@
           "refId": "A"
         }
       ]
+    },
+    {
+      "collapsed": false,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 182 },
+      "id": 152,
+      "title": "Backlog-vs-Fresh-Intake Lane Fairness (#selfhost-lane-observability)",
+      "type": "row"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "thresholds" },
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "yellow", "value": 10 },
+              { "color": "red", "value": 30 }
+            ]
+          },
+          "unit": "short"
+        }
+      },
+      "gridPos": { "h": 4, "w": 4, "x": 0, "y": 183 },
+      "id": 153,
+      "options": {
+        "colorMode": "background",
+        "graphMode": "none",
+        "justifyMode": "auto",
+        "orientation": "auto",
+        "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false },
+        "textMode": "auto"
+      },
+      "title": "Backlog-Convergence Pending",
+      "type": "stat",
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "gittensory_queue_backlog_convergence_pending",
+          "legendFormat": "backlog pending"
+        }
+      ]
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "thresholds" },
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "yellow", "value": 10 },
+              { "color": "red", "value": 30 }
+            ]
+          },
+          "unit": "short"
+        }
+      },
+      "gridPos": { "h": 4, "w": 4, "x": 4, "y": 183 },
+      "id": 154,
+      "options": {
+        "colorMode": "background",
+        "graphMode": "none",
+        "justifyMode": "auto",
+        "orientation": "auto",
+        "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false },
+        "textMode": "auto"
+      },
+      "title": "Fresh-Intake Pending",
+      "type": "stat",
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "gittensory_queue_fresh_intake_pending",
+          "legendFormat": "fresh pending"
+        }
+      ]
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": {
+        "defaults": { "color": { "mode": "palette-classic" }, "custom": { "lineWidth": 2, "fillOpacity": 10 }, "unit": "short" }
+      },
+      "gridPos": { "h": 6, "w": 16, "x": 8, "y": 183 },
+      "id": 155,
+      "options": {
+        "legend": { "calcs": ["lastNotNull"], "displayMode": "table", "placement": "bottom" },
+        "tooltip": { "mode": "multi", "sort": "desc" }
+      },
+      "title": "GitHub REST Rate Limit Remaining (by scope)",
+      "description": "The NEWEST observed x-ratelimit-remaining per key_scope -- unlike gittensory_github_rest_rate_limit_observations_total (a bucketed rate() counter), this is the actual current remaining count.",
+      "type": "timeseries",
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "gittensory_github_rest_rate_limit_remaining",
+          "legendFormat": "{{key_scope}}",
+          "refId": "A"
+        }
+      ]
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": {
+        "defaults": { "color": { "mode": "palette-classic" }, "custom": { "lineWidth": 2, "fillOpacity": 10 }, "unit": "ops" }
+      },
+      "gridPos": { "h": 6, "w": 12, "x": 0, "y": 189 },
+      "id": 156,
+      "options": {
+        "legend": { "calcs": ["lastNotNull"], "displayMode": "table", "placement": "bottom" },
+        "tooltip": { "mode": "multi", "sort": "desc" }
+      },
+      "title": "Foreground Claims by Lane (rate)",
+      "type": "timeseries",
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "sum by (lane) (rate(gittensory_jobs_claimed_by_lane_total[5m])) or vector(0)",
+          "legendFormat": "{{lane}}",
+          "refId": "A"
+        }
+      ]
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": { "defaults": { "unit": "short" } },
+      "gridPos": { "h": 6, "w": 12, "x": 12, "y": 189 },
+      "id": 157,
+      "options": {
+        "showHeader": true,
+        "cellHeight": "sm",
+        "footer": { "show": false, "reducer": ["sum"], "fields": "" }
+      },
+      "title": "Top Repos by Backlog Depth",
+      "description": "Top-10 repos by backlog-convergence pending depth, recomputed fresh every scrape -- bounded so a large multi-repo self-host install never explodes this panel's series count.",
+      "type": "table",
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "gittensory_queue_backlog_by_repo",
+          "format": "table",
+          "instant": true,
+          "legendFormat": "__auto",
+          "refId": "A"
+        }
+      ],
+      "transformations": [
+        {
+          "id": "organize",
+          "options": {
+            "excludeByName": { "Time": true, "__name__": true, "job": true, "instance": true },
+            "indexByName": { "repo": 0, "Value": 1 }
+          }
+        }
+      ]
     }
   ],
   "refresh": "30s",

packages/gittensory-engine/src/goal-model.ts

@@ -0,0 +1,91 @@
+import type { MinerGoalSpec } from "./miner-goal-spec.js";
+
+export type GoalModelInput = {
+  candidatePaths: string[];
+  candidateLabels: string[];
+  goalSpec: MinerGoalSpec;
+};
+
+function normalizeLabels(labels: readonly string[]): string[] {
+  return labels
+    .filter((label): label is string => typeof label === "string")
+    .map((label) => label.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function normalizePathForMatch(path: string): string {
+  return String(path ?? "").replace(/\\/g, "/").toLowerCase();
+}
+
+function compileGlobMatcher(pattern: string): (path: string) => boolean {
+  const normalizedPattern = normalizePathForMatch(pattern);
+  if (!normalizedPattern) return () => false;
+  let regex = "^";
+  for (let i = 0; i < normalizedPattern.length; i++) {
+    const ch = normalizedPattern[i];
+    const next = normalizedPattern[i + 1];
+    if (ch === "*" && next === "*") {
+      const afterDoubleStar = normalizedPattern[i + 2];
+      if (afterDoubleStar === "/") {
+        regex += "(?:.*/)?";
+        i += 2;
+      } else {
+        regex += ".*";
+        i++;
+      }
+    } else if (ch === "*") {
+      regex += "[^/]*";
+    } else if (ch === "?") {
+      regex += "[^/]";
+    } else if (/[.+^$(){}|[\]\\]/.test(ch ?? "")) {
+      regex += "\\" + ch;
+    } else {
+      regex += ch;
+    }
+  }
+  regex += "$";
+  const compiled = new RegExp(regex);
+  return (path: string) => {
+    const normalized = normalizePathForMatch(path);
+    if (!normalized) return false;
+    return compiled.test(normalized);
+  };
+}
+
+function matchesAnyLabel(candidateLabels: readonly string[], goalLabels: readonly string[]): boolean {
+  if (goalLabels.length === 0) return false;
+  const normalizedCandidate = normalizeLabels(candidateLabels);
+  const normalizedGoal = normalizeLabels(goalLabels);
+  return normalizedGoal.some((label) => normalizedCandidate.includes(label));
+}
+
+function matchesAnyPath(candidatePaths: readonly string[], goalPaths: readonly string[]): boolean {
+  if (goalPaths.length === 0) return false;
+  return goalPaths.some((pattern) => {
+    const matcher = compileGlobMatcher(pattern);
+    return candidatePaths.some((path) => matcher(path));
+  });
+}
+
+export function computeLaneFit(input: GoalModelInput): number {
+  const { candidatePaths, candidateLabels, goalSpec } = input;
+  if (matchesAnyPath(candidatePaths, goalSpec.blockedPaths)) {
+    return 0;
+  }
+  if (matchesAnyLabel(candidateLabels, goalSpec.blockedLabels)) {
+    return 0;
+  }
+  const hasPathCriteria = goalSpec.wantedPaths.length > 0;
+  const hasLabelCriteria = goalSpec.preferredLabels.length > 0;
+  if (!hasPathCriteria && !hasLabelCriteria) {
+    return 0.5;
+  }
+  const pathMatches = hasPathCriteria && matchesAnyPath(candidatePaths, goalSpec.wantedPaths);
+  const labelMatches = hasLabelCriteria && matchesAnyLabel(candidateLabels, goalSpec.preferredLabels);
+  if (!pathMatches && !labelMatches) {
+    return 0;
+  }
+  const activeDimensions = (hasPathCriteria ? 1 : 0) + (hasLabelCriteria ? 1 : 0);
+  const matchedDimensions = (pathMatches ? 1 : 0) + (labelMatches ? 1 : 0);
+  return matchedDimensions / activeDimensions;
+}

packages/gittensory-engine/src/governor-ledger.ts

@@ -1,5 +1,3 @@
-import { isDeepStrictEqual } from "node:util";
-
 /** Immutable governor decision vocabulary — unknown values fail closed before insert. */
 export const GOVERNOR_LEDGER_EVENT_TYPES = Object.freeze([
   "allowed",
@@ -46,6 +44,27 @@ function normalizeOptionalRepoFullName(repoFullName: unknown): string | null {
   return `${owner}/${repo}`;
 }
 
+// Structural equality between a JSON.parse() result and the plain object it was stringified from. One side is
+// always JSON-safe (parsed from JSON text); this only needs to compare plain objects/arrays/primitives, not the
+// full generality of node:util's isDeepStrictEqual (no Dates/RegExp/Maps/getters/symbols to worry about) — this
+// package's tsconfig deliberately sets `types: []` (no Node ambient types leak into its public .d.ts surface),
+// so importing "node:util" here isn't viable; a small local check avoids that entirely.
+function jsonRoundTripEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (typeof a !== "object") return false;
+  const aIsArray = Array.isArray(a);
+  if (aIsArray !== Array.isArray(b)) return false;
+  if (aIsArray) {
+    const bArr = b as unknown[];
+    const aArr = a as unknown[];
+    return aArr.length === bArr.length && aArr.every((value, index) => jsonRoundTripEqual(value, bArr[index]));
+  }
+  const aKeys = Object.keys(a as object);
+  const bRecord = b as Record<string, unknown>;
+  return aKeys.length === Object.keys(bRecord).length && aKeys.every((key) => Object.hasOwn(bRecord, key) && jsonRoundTripEqual((a as Record<string, unknown>)[key], bRecord[key]));
+}
+
 function serializePayload(payload: unknown): string {
   if (payload === undefined) return "{}";
   if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
@@ -57,7 +76,7 @@ function serializePayload(payload: unknown): string {
   } catch {
     throw new Error("invalid_payload");
   }
-  if (!isDeepStrictEqual(JSON.parse(json), payload)) {
+  if (!jsonRoundTripEqual(JSON.parse(json), payload)) {
     throw new Error("invalid_payload");
   }
   return json;

packages/gittensory-engine/src/index.ts

@@ -45,6 +45,10 @@ export {
   type FreshnessIssue,
 } from "./opportunity-freshness.js";
 export { computeOpportunityCompetition } from "./opportunity-competition.js";
+export {
+  computeLaneFit,
+  type GoalModelInput,
+} from "./goal-model.js";
 export {
   classifyContributorFit,
   type ContributorFit,

packages/gittensory-engine/src/opportunity-freshness.ts

@@ -27,9 +27,9 @@ function pickTimestamp(issue: FreshnessIssue): string | null {
 }
 
 function issueAgeDays(value: string | null, nowMs: number): number {
-  if (!value) return 0;
+  if (!value) return Number.POSITIVE_INFINITY;
   const parsed = Date.parse(value);
-  if (!Number.isFinite(parsed)) return 0;
+  if (!Number.isFinite(parsed)) return Number.POSITIVE_INFINITY;
   return Math.floor((nowMs - parsed) / 86_400_000);
 }