@loopover/miner 0.1.0

package/lib/worktree-allocator.js

@@ -0,0 +1,262 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+// Git-worktree-per-attempt allocator (#4297): durable local bookkeeping for which worktree paths are
+// allocated to which fleet attempts. Mirrors the package's existing local-store pattern (run-state.js,
+// claim-ledger.js, portfolio-queue.js) — plain JS + node:sqlite, never phones home.
+
+const defaultDbFileName = "worktree-allocator.sqlite3";
+const defaultWorktreeDirName = "worktrees";
+const defaultMaxConcurrency = 2;
+let defaultWorktreeAllocator = null;
+
+export function resolveWorktreeAllocatorDbPath(env = process.env) {
+  const explicitPath = typeof env.GITTENSORY_MINER_WORKTREE_ALLOCATOR_DB === "string"
+    ? env.GITTENSORY_MINER_WORKTREE_ALLOCATOR_DB.trim()
+    : "";
+  if (explicitPath) return explicitPath;
+
+  const explicitConfigDir = typeof env.GITTENSORY_MINER_CONFIG_DIR === "string"
+    ? env.GITTENSORY_MINER_CONFIG_DIR.trim()
+    : "";
+  if (explicitConfigDir) return join(explicitConfigDir, defaultDbFileName);
+
+  const configHome = typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim()
+    ? env.XDG_CONFIG_HOME.trim()
+    : join(homedir(), ".config");
+  return join(configHome, "gittensory-miner", defaultDbFileName);
+}
+
+export function resolveWorktreeBaseDir(env = process.env) {
+  const explicitPath = typeof env.GITTENSORY_MINER_WORKTREE_DIR === "string"
+    ? env.GITTENSORY_MINER_WORKTREE_DIR.trim()
+    : "";
+  if (explicitPath) return explicitPath;
+
+  const explicitConfigDir = typeof env.GITTENSORY_MINER_CONFIG_DIR === "string"
+    ? env.GITTENSORY_MINER_CONFIG_DIR.trim()
+    : "";
+  if (explicitConfigDir) return join(explicitConfigDir, defaultWorktreeDirName);
+
+  const configHome = typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim()
+    ? env.XDG_CONFIG_HOME.trim()
+    : join(homedir(), ".config");
+  return join(configHome, "gittensory-miner", defaultWorktreeDirName);
+}
+
+function normalizeDbPath(dbPath) {
+  const path = (dbPath ?? resolveWorktreeAllocatorDbPath()).trim();
+  if (!path) throw new Error("invalid_worktree_allocator_db_path");
+  return path;
+}
+
+function normalizeWorktreeBaseDir(worktreeBaseDir) {
+  const path = (worktreeBaseDir ?? resolveWorktreeBaseDir()).trim();
+  if (!path) throw new Error("invalid_worktree_base_dir");
+  return path;
+}
+
+function normalizeMaxConcurrency(value) {
+  if (value === undefined || value === null) return defaultMaxConcurrency;
+  if (!Number.isInteger(value) || value < 1) throw new Error("invalid_max_concurrency");
+  return value;
+}
+
+function normalizeRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const [owner, repo, extra] = repoFullName.trim().split("/");
+  if (!owner || !repo || extra !== undefined) throw new Error("invalid_repo_full_name");
+  return `${owner}/${repo}`;
+}
+
+function normalizeAttemptId(attemptId) {
+  if (typeof attemptId !== "string") throw new Error("invalid_attempt_id");
+  const trimmed = attemptId.trim();
+  if (!trimmed) throw new Error("invalid_attempt_id");
+  return trimmed;
+}
+
+export function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // ESRCH = no such process; EPERM (or similar) means the process exists but we lack signal rights.
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ESRCH"
+      ? false
+      : true;
+  }
+}
+
+function rowToAllocation(row) {
+  return {
+    slotIndex: row.slot_index,
+    worktreePath: row.worktree_path,
+    attemptId: row.attempt_id,
+    repoFullName: row.repo_full_name,
+    status: row.status,
+    ownerPid: row.owner_pid,
+    allocatedAt: row.allocated_at,
+  };
+}
+
+function ensureSlotTable(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS worktree_slots (
+      slot_index INTEGER PRIMARY KEY,
+      worktree_path TEXT NOT NULL UNIQUE,
+      attempt_id TEXT UNIQUE,
+      repo_full_name TEXT,
+      status TEXT NOT NULL CHECK (status IN ('free', 'active')),
+      owner_pid INTEGER,
+      allocated_at TEXT
+    )
+  `);
+}
+
+function ensureSlots(db, worktreeBaseDir, maxConcurrency) {
+  mkdirSync(worktreeBaseDir, { recursive: true, mode: 0o700 });
+  const insert = db.prepare(`
+    INSERT OR IGNORE INTO worktree_slots (slot_index, worktree_path, status)
+    VALUES (?, ?, 'free')
+  `);
+  for (let slotIndex = 0; slotIndex < maxConcurrency; slotIndex += 1) {
+    const worktreePath = join(worktreeBaseDir, `slot-${slotIndex}`);
+    insert.run(slotIndex, worktreePath);
+    mkdirSync(worktreePath, { recursive: true, mode: 0o700 });
+  }
+}
+
+function reclaimOrphanedAllocations(db) {
+  const orphans = db
+    .prepare("SELECT slot_index, owner_pid FROM worktree_slots WHERE status = 'active'")
+    .all();
+  const reclaim = db.prepare(`
+    UPDATE worktree_slots
+    SET status = 'free', attempt_id = NULL, repo_full_name = NULL, owner_pid = NULL, allocated_at = NULL
+    WHERE slot_index = ?
+  `);
+  for (const row of orphans) {
+    if (row.owner_pid !== null && isProcessAlive(row.owner_pid)) continue;
+    reclaim.run(row.slot_index);
+  }
+}
+
+/**
+ * Opens the local worktree allocator store. Reclaims orphaned active slots from dead owner processes on startup.
+ */
+export function openWorktreeAllocator(options = {}) {
+  const resolvedPath = normalizeDbPath(options.dbPath);
+  const worktreeBaseDir = normalizeWorktreeBaseDir(options.worktreeBaseDir);
+  const maxConcurrency = normalizeMaxConcurrency(options.maxConcurrency);
+  const processPid = Number.isInteger(options.processPid) ? options.processPid : process.pid;
+
+  mkdirSync(dirname(resolvedPath), { recursive: true, mode: 0o700 });
+  const db = new DatabaseSync(resolvedPath);
+  chmodSync(resolvedPath, 0o600);
+  db.exec("PRAGMA busy_timeout = 5000");
+  ensureSlotTable(db);
+  ensureSlots(db, worktreeBaseDir, maxConcurrency);
+  reclaimOrphanedAllocations(db);
+
+  const getByAttempt = db.prepare(
+    "SELECT slot_index, worktree_path, attempt_id, repo_full_name, status, owner_pid, allocated_at FROM worktree_slots WHERE attempt_id = ?",
+  );
+  const countActive = db.prepare("SELECT COUNT(*) AS count FROM worktree_slots WHERE status = 'active'");
+  const selectFreeSlot = db.prepare(`
+    SELECT slot_index, worktree_path, attempt_id, repo_full_name, status, owner_pid, allocated_at
+    FROM worktree_slots
+    WHERE status = 'free'
+    ORDER BY slot_index
+    LIMIT 1
+  `);
+  const markActive = db.prepare(`
+    UPDATE worktree_slots
+    SET status = 'active', attempt_id = ?, repo_full_name = ?, owner_pid = ?, allocated_at = ?
+    WHERE slot_index = ?
+  `);
+  const releaseByAttempt = db.prepare(`
+    UPDATE worktree_slots
+    SET status = 'free', attempt_id = NULL, repo_full_name = NULL, owner_pid = NULL, allocated_at = NULL
+    WHERE attempt_id = ? AND status = 'active'
+    RETURNING slot_index, worktree_path, attempt_id, repo_full_name, status, owner_pid, allocated_at
+  `);
+  const listSlots = db.prepare(
+    "SELECT slot_index, worktree_path, attempt_id, repo_full_name, status, owner_pid, allocated_at FROM worktree_slots ORDER BY slot_index",
+  );
+
+  const allocator = {
+    dbPath: resolvedPath,
+    worktreeBaseDir,
+    maxConcurrency,
+    processPid,
+    acquire(attemptId, repoFullName) {
+      const normalizedAttempt = normalizeAttemptId(attemptId);
+      const normalizedRepo = normalizeRepoFullName(repoFullName);
+      const existing = getByAttempt.get(normalizedAttempt);
+      if (existing?.status === "active") return rowToAllocation(existing);
+
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const raced = getByAttempt.get(normalizedAttempt);
+        if (raced?.status === "active") {
+          db.exec("COMMIT");
+          return rowToAllocation(raced);
+        }
+        const activeCount = countActive.get().count;
+        if (activeCount >= maxConcurrency) throw new Error("worktree_capacity_exceeded");
+        const slot = selectFreeSlot.get();
+        if (!slot) throw new Error("worktree_capacity_exceeded");
+        const allocatedAt = new Date().toISOString();
+        markActive.run(normalizedAttempt, normalizedRepo, processPid, allocatedAt, slot.slot_index);
+        db.exec("COMMIT");
+        return rowToAllocation({
+          ...slot,
+          attempt_id: normalizedAttempt,
+          repo_full_name: normalizedRepo,
+          status: "active",
+          owner_pid: processPid,
+          allocated_at: allocatedAt,
+        });
+      } catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+      }
+    },
+    release(attemptId) {
+      const normalizedAttempt = normalizeAttemptId(attemptId);
+      const row = releaseByAttempt.get(normalizedAttempt);
+      return row ? rowToAllocation(row) : null;
+    },
+    listSlots() {
+      return listSlots.all().map(rowToAllocation);
+    },
+    close() {
+      db.close();
+    },
+  };
+
+  return allocator;
+}
+
+function getDefaultWorktreeAllocator() {
+  defaultWorktreeAllocator ??= openWorktreeAllocator();
+  return defaultWorktreeAllocator;
+}
+
+export function acquireWorktree(attemptId, repoFullName) {
+  return getDefaultWorktreeAllocator().acquire(attemptId, repoFullName);
+}
+
+export function releaseWorktree(attemptId) {
+  return getDefaultWorktreeAllocator().release(attemptId);
+}
+
+export function closeDefaultWorktreeAllocator() {
+  if (!defaultWorktreeAllocator) return;
+  defaultWorktreeAllocator.close();
+  defaultWorktreeAllocator = null;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@loopover/miner",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "description": "Foundation CLI for the local Gittensory miner runtime.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JSONbored/gittensory.git",
+    "directory": "packages/gittensory-miner"
+  },
+  "homepage": "https://github.com/JSONbored/gittensory#readme",
+  "bugs": {
+    "url": "https://github.com/JSONbored/gittensory/issues"
+  },
+  "keywords": [
+    "gittensor",
+    "gittensory",
+    "miner",
+    "cli",
+    "agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "gittensory-miner": "bin/gittensory-miner.js",
+    "gittensory-miner-mcp": "bin/gittensory-miner-mcp.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "docs",
+    "schema",
+    "DEPLOYMENT.md",
+    "Dockerfile",
+    "expected-engine.version"
+  ],
+  "scripts": {
+    "build": "node --check bin/gittensory-miner.js && node --check bin/gittensory-miner-mcp.js && node --check lib/ams-policy.js && node --check lib/attempt-cli.js && node --check lib/attempt-input-builder.js && node --check lib/attempt-log.js && node --check lib/attempt-runner.js && node --check lib/attempt-worktree.js && node --check lib/calibration-run.js && node --check lib/calibration-types.js && node --check lib/calibration.js && node --check lib/ci-poller.js && node --check lib/claim-adjudication.js && node --check lib/claim-conflict-resolver.js && node --check lib/claim-ledger-cli.js && node --check lib/claim-ledger-expiry.js && node --check lib/claim-ledger.js && node --check lib/cli.js && node --check lib/coding-agent-construction.js && node --check lib/coding-agent-house-rules.js && node --check lib/coding-task-spec.js && node --check lib/deny-check.js && node --check lib/deny-hook-synthesis.js && node --check lib/deny-hooks.js && node --check lib/deployment-docs-audit.js && node --check lib/discover-cli.js && node --check lib/event-ledger-cli.js && node --check lib/event-ledger.js && node --check lib/execute-local-write.js && node --check lib/feasibility-cli.js && node --check lib/governor-action-mode.js && node --check lib/governor-chokepoint-persisted.js && node --check lib/governor-chokepoint.js && node --check lib/governor-kill-switch.js && node --check lib/governor-ledger-cli.js && node --check lib/governor-ledger.js && node --check lib/governor-open-pr.js && node --check lib/governor-pause-cli.js && node --check lib/governor-run-halt.js && node --check lib/governor-state.js && node --check lib/governor-write-rate-limit.js && node --check lib/harness-submission-trigger.js && node --check lib/laptop-init.js && node --check lib/live-issue-snapshot.js && node --check lib/local-store.js && node --check lib/logger.js && node --check lib/loop-cli.js && node --check lib/loop-closure.js && node --check lib/loop-reentry.js && node --check lib/manage-poll.js && node --check lib/manage-status.js && node --check lib/metrics-cli.js && node --check lib/miner-goal-spec.js && node --check lib/opportunity-fanout.js && node --check lib/opportunity-ranker.js && node --check lib/orb-export.js && node --check lib/plan-store-cli.js && node --check lib/plan-store.js && node --check lib/policy-doc-cache.js && node --check lib/policy-verdict-cache.js && node --check lib/portfolio-dashboard.js && node --check lib/portfolio-discovery.js && node --check lib/portfolio-queue-cli.js && node --check lib/portfolio-queue-manager.js && node --check lib/portfolio-queue.js && node --check lib/portfolio-queue-expiry.js && node --check lib/pr-disposition-poller.js && node --check lib/pr-number-parse.js && node --check lib/pr-outcome.js && node --check lib/prediction-ledger.js && node --check lib/pretooluse-hook.js && node --check lib/purge-cli.js && node --check lib/rejection-signal.js && node --check lib/rejection-state-machine.js && node --check lib/rejection-templates.js && node --check lib/replay-objective-anchor.js && node --check lib/replay-snapshot.js && node --check lib/replay-task-generation.js && node --check lib/repo-clone.js && node --check lib/run-state-cli.js && node --check lib/run-state.js && node --check lib/self-review-context.js && node --check lib/slop-assessment.js && node --check lib/stack-detection.js && node --check lib/status.js && node --check lib/submission-freshness-check.js && node --check lib/update-check.js && node --check lib/version.js && node --check lib/worktree-allocator.js"
+  },
+  "dependencies": {
+    "@loopover/engine": "*",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  }
+}

package/schema/miner-goal-spec.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jsonbored.dev/schemas/gittensory-miner-goal-spec.json",
+  "title": "MinerGoalSpec",
+  "description": "Per-repo miner configuration parsed from `.gittensory-miner.yml` (see packages/gittensory-miner/docs/miner-goal-spec.md).",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "minerEnabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether autonomous miners may target this repo. Default: true."
+    },
+    "wantedPaths": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "default": [],
+      "description": "Work areas a miner should prefer. Glob list. Default: []."
+    },
+    "blockedPaths": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "default": [],
+      "description": "Paths a miner must skip. Glob list. Default: []."
+    },
+    "preferredLabels": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "default": [],
+      "description": "Issue labels a miner should favor. Default: []."
+    },
+    "blockedLabels": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "default": [],
+      "description": "Issue labels a miner must skip. Default: []."
+    },
+    "maxConcurrentClaims": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1,
+      "description": "Maximum active claims one miner may hold on this repo. Default: 1."
+    },
+    "issueDiscoveryPolicy": {
+      "type": "string",
+      "enum": ["encouraged", "neutral", "discouraged"],
+      "default": "neutral",
+      "description": "How strongly opening discovery issues is encouraged. Default: neutral."
+    },
+    "feasibilityGate": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": { "enabled": true, "suppressedReasons": [] },
+      "description": "Per-repo tuning for the feasibility gate a miner consults before starting work. Default: { enabled: true, suppressedReasons: [] }.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the feasibility gate is consulted at all before a miner starts work. Default: true."
+        },
+        "suppressedReasons": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "default": [],
+          "description": "buildFeasibilityVerdict avoid/raise reason codes this repo wants ignored. Default: []."
+        }
+      }
+    },
+    "selfPlagiarism": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": { "similarityThreshold": 0.85 },
+      "description": "Self-plagiarism throttle consulted before open_pr (#2345). Default: { similarityThreshold: 0.85 }.",
+      "properties": {
+        "similarityThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.85,
+          "description": "Jaccard similarity threshold for near-duplicate diff fingerprints. Default: 0.85."
+        }
+      }
+    },
+    "killSwitch": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": { "paused": false },
+      "description": "Per-repo kill-switch consulted by the Governor chokepoint before every write action (#2341). Default: { paused: false }.",
+      "properties": {
+        "paused": {
+          "type": "boolean",
+          "default": false,
+          "description": "Halts all miner WRITE actions for this repo without deregistering it from targeting/discovery. Default: false."
+        }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": { "liveModeOptIn": null },
+      "description": "Per-repo dry-run/live execution opt-in consulted by the Governor chokepoint (#2342). Default: { liveModeOptIn: null }.",
+      "properties": {
+        "liveModeOptIn": {
+          "type": ["string", "null"],
+          "default": null,
+          "description": "Must equal exactly \"live\" to opt this repo into live write execution; any other value stays dry-run. Also requires the operator's own global opt-in (GITTENSORY_MINER_LIVE_MODE=live) unless the operator's own config already grants it. Default: null."
+        }
+      }
+    }
+  }
+}