@triflux/remote 10.0.1 → 10.25.1

package/hub/team/swarm-intent.mjs

@@ -0,0 +1,216 @@
+// hub/team/swarm-intent.mjs — X-Intent helper utilities for semantic merge awareness
+
+const INTENT_TRAILER_REGEX = /^X-Intent:\s*(.+)$/m;
+
+function normalizeText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeTouches(touches) {
+  if (!Array.isArray(touches)) return null;
+  return touches
+    .filter((item) => typeof item === "string")
+    .map((item) => item.trim().replace(/\\/g, "/"))
+    .filter(Boolean);
+}
+
+function normalizeIntent(intentObj) {
+  if (!intentObj || typeof intentObj !== "object" || Array.isArray(intentObj)) {
+    return null;
+  }
+
+  const scope = normalizeText(intentObj.scope);
+  const action = normalizeText(intentObj.action);
+  const reason = normalizeText(intentObj.reason);
+  const touches = normalizeTouches(intentObj.touches);
+
+  if (!scope || !action || !reason || !touches) {
+    return null;
+  }
+
+  return {
+    scope,
+    action,
+    reason,
+    touches,
+    invariant: normalizeText(intentObj.invariant),
+    conflictsWith: normalizeText(intentObj.conflictsWith),
+  };
+}
+
+function fallbackIntent(llmResponse) {
+  const responseText = String(llmResponse ?? "");
+  return {
+    scope: "unknown",
+    action: "unknown",
+    reason: responseText.slice(0, 100),
+    touches: [],
+    invariant: "",
+    conflictsWith: "",
+  };
+}
+
+function includesEitherWay(a, b) {
+  if (!a || !b) return false;
+  return a.includes(b) || b.includes(a);
+}
+
+function hasConflict(intentA, intentB) {
+  const conflictsWith = normalizeText(intentA?.conflictsWith).toLowerCase();
+  const scope = normalizeText(intentB?.scope).toLowerCase();
+  const action = normalizeText(intentB?.action).toLowerCase();
+
+  if (!conflictsWith) return false;
+  return (
+    includesEitherWay(conflictsWith, scope) ||
+    includesEitherWay(conflictsWith, action)
+  );
+}
+
+function getTouchesOverlap(intentA, intentB) {
+  const touchesA = new Set(
+    (normalizeTouches(intentA?.touches) ?? []).map((item) =>
+      item.toLowerCase(),
+    ),
+  );
+  const touchesB = (normalizeTouches(intentB?.touches) ?? []).map((item) =>
+    item.toLowerCase(),
+  );
+  return touchesB.filter((item) => touchesA.has(item));
+}
+
+/**
+ * Build prompts for an LLM to generate an X-Intent JSON object.
+ * @param {string[]} changedFiles
+ * @param {string} commitDiff
+ * @param {string} taskContext
+ * @returns {{ systemPrompt: string, userPrompt: string }}
+ */
+export function generateIntentPrompt(changedFiles, commitDiff, taskContext) {
+  const files = Array.isArray(changedFiles)
+    ? changedFiles.filter((filePath) => typeof filePath === "string")
+    : [];
+  const diffSnippet = String(commitDiff ?? "").slice(0, 4000);
+  const context = String(taskContext ?? "").trim();
+
+  return {
+    systemPrompt:
+      "You generate commit intent metadata for semantic merge awareness. Return only valid JSON with keys: scope, action, reason, touches, invariant, conflictsWith.",
+    userPrompt: [
+      "Create an intent object from the following commit context.",
+      "- scope/action/reason must be concise strings.",
+      "- touches must be an array of touched file paths.",
+      "- invariant/conflictsWith should be strings (empty if unknown).",
+      "- Return JSON only (no markdown).",
+      "",
+      `Task context:\n${context || "(none provided)"}`,
+      "",
+      `Changed files (${files.length}):\n${files.join("\n") || "(none)"}`,
+      "",
+      "Commit diff (first 4000 chars):",
+      diffSnippet || "(empty)",
+    ].join("\n"),
+  };
+}
+
+/**
+ * Format an intent object into an X-Intent commit trailer.
+ * @param {object} intentObj
+ * @returns {string}
+ */
+export function formatIntentTrailer(intentObj) {
+  return `X-Intent: ${JSON.stringify(intentObj)}`;
+}
+
+/**
+ * Parse an X-Intent trailer from a commit message.
+ * @param {string} commitMessage
+ * @returns {object | null}
+ */
+export function parseIntentTrailer(commitMessage) {
+  const message = String(commitMessage ?? "");
+  const match = message.match(INTENT_TRAILER_REGEX);
+  if (!match) return null;
+
+  try {
+    return JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Classify the relation between two intents.
+ * @param {object} intentA
+ * @param {object} intentB
+ * @returns {{ relation: "complementary" | "complementary-risky" | "contradictory" | "independent", reason: string }}
+ */
+export function classifyIntentPair(intentA, intentB) {
+  if (hasConflict(intentA, intentB) || hasConflict(intentB, intentA)) {
+    return {
+      relation: "contradictory",
+      reason:
+        "conflictsWith on one intent matches the other intent scope/action",
+    };
+  }
+
+  const scopeA = normalizeText(intentA?.scope).toLowerCase();
+  const scopeB = normalizeText(intentB?.scope).toLowerCase();
+
+  if (scopeA && scopeB && scopeA === scopeB) {
+    const overlap = getTouchesOverlap(intentA, intentB);
+    if (overlap.length > 0) {
+      return {
+        relation: "complementary-risky",
+        reason: `same scope with overlapping touched files: ${overlap.join(", ")}`,
+      };
+    }
+
+    return {
+      relation: "complementary",
+      reason:
+        "same scope with no conflicting intent and no touched-file overlap",
+    };
+  }
+
+  return {
+    relation: "independent",
+    reason: "different scopes and no conflictsWith match detected",
+  };
+}
+
+/**
+ * Build a validated intent object from raw LLM response text.
+ * @param {string} llmResponse
+ * @returns {{ scope: string, action: string, reason: string, touches: string[], invariant: string, conflictsWith: string }}
+ */
+export function buildIntentFromLLMResponse(llmResponse) {
+  const responseText = String(llmResponse ?? "").trim();
+  const candidates = [];
+
+  const codeBlockRegex = /```(?:json)?\s*([\s\S]*?)```/gi;
+  for (const match of responseText.matchAll(codeBlockRegex)) {
+    if (match[1]) candidates.push(match[1].trim());
+  }
+
+  candidates.push(responseText);
+
+  const firstBrace = responseText.indexOf("{");
+  const lastBrace = responseText.lastIndexOf("}");
+  if (firstBrace >= 0 && lastBrace > firstBrace) {
+    candidates.push(responseText.slice(firstBrace, lastBrace + 1));
+  }
+
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    try {
+      const parsed = JSON.parse(candidate);
+      const normalized = normalizeIntent(parsed);
+      if (normalized) return normalized;
+    } catch {
+      // ignore parse failures and continue trying other candidates
+    }
+  }
+
+  return fallbackIntent(responseText);
+}

package/hub/team/swarm-locks.mjs

@@ -3,11 +3,36 @@
 // Lock state is kept in-memory (single-process hypervisor) with optional
 // JSON persistence to .triflux/swarm-locks.json for crash recovery.
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { dirname, resolve, relative } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
 
 const LOCK_TTL_MS = 10 * 60_000; // 10 minutes default TTL
 
+// Distribution-critical paths. A swarm worker that modifies these without
+// having them explicitly listed in its shard lease is almost certainly a
+// recovery-patch fallout (worker exited before commit, hypervisor saved
+// patch with destructive `+++ /dev/null` deletions). Block by default;
+// override via validateChanges options.sensitiveDeny.
+//
+// Paths use POSIX separators (matches normalizePath output).
+export const SENSITIVE_PATH_PREFIXES = [
+  ".claude-plugin/",
+  "bin/",
+  ".github/workflows/",
+];
+export const SENSITIVE_PATH_FILES = [
+  ".gitignore",
+  ".npmignore",
+  "package.json",
+  "package-lock.json",
+  "biome.json",
+];
+
+export const DEFAULT_SENSITIVE_DENY = Object.freeze({
+  prefixes: Object.freeze([...SENSITIVE_PATH_PREFIXES]),
+  files: Object.freeze([...SENSITIVE_PATH_FILES]),
+});
+
 /**
  * Swarm lock manager factory.
  * @param {object} [opts]
@@ -17,11 +42,7 @@ const LOCK_TTL_MS = 10 * 60_000; // 10 minutes default TTL
  * @returns {SwarmLockManager}
  */
 export function createSwarmLocks(opts = {}) {
-  const {
-    repoRoot = process.cwd(),
-    persistPath,
-    ttlMs = LOCK_TTL_MS,
-  } = opts;
+  const { repoRoot = process.cwd(), persistPath, ttlMs = LOCK_TTL_MS } = opts;
 
   /** @type {Map<string, LockEntry>} normalized relative path → lock */
   const locks = new Map();
@@ -30,13 +51,41 @@ export function createSwarmLocks(opts = {}) {
 
   function normalizePath(filePath) {
     const abs = resolve(repoRoot, filePath);
-    return relative(repoRoot, abs).replace(/\\/g, '/');
+    return relative(repoRoot, abs).replace(/\\/g, "/");
   }
 
   function now() {
     return Date.now();
   }
 
+  function normalizeLeaseType(leaseType) {
+    return leaseType === "shared-read" ? "shared-read" : "exclusive";
+  }
+
+  function normalizeSessionMeta(sessionMeta) {
+    return sessionMeta ?? null;
+  }
+
+  function normalizeEntry(entry) {
+    return {
+      workerId: entry.workerId,
+      acquiredAt: entry.acquiredAt,
+      leaseType: normalizeLeaseType(entry.leaseType),
+      sessionMeta: normalizeSessionMeta(entry.sessionMeta),
+    };
+  }
+
+  function hasConflict(existing, requesterId, requestedLeaseType) {
+    if (!existing || existing.workerId === requesterId) return false;
+    if (
+      existing.leaseType === "shared-read" &&
+      requestedLeaseType === "shared-read"
+    ) {
+      return false;
+    }
+    return true;
+  }
+
   function isExpired(entry) {
     return now() - entry.acquiredAt > ttlMs;
   }
@@ -56,21 +105,25 @@ export function createSwarmLocks(opts = {}) {
       const data = Object.fromEntries(
         [...locks].map(([k, v]) => [k, { ...v }]),
       );
-      writeFileSync(persistPath, JSON.stringify(data, null, 2), 'utf8');
-    } catch { /* best-effort */ }
+      writeFileSync(persistPath, JSON.stringify(data, null, 2), "utf8");
+    } catch {
+      /* best-effort */
+    }
   }
 
   function restore() {
     if (!persistPath || !existsSync(persistPath)) return;
     try {
-      const data = JSON.parse(readFileSync(persistPath, 'utf8'));
+      const data = JSON.parse(readFileSync(persistPath, "utf8"));
       const ts = now();
       for (const [path, entry] of Object.entries(data)) {
         if (ts - entry.acquiredAt <= ttlMs) {
-          locks.set(path, entry);
+          locks.set(path, normalizeEntry(entry));
         }
       }
-    } catch { /* corrupted file — start fresh */ }
+    } catch {
+      /* corrupted file — start fresh */
+    }
   }
 
   // restore on creation
@@ -82,23 +135,42 @@ export function createSwarmLocks(opts = {}) {
    * Acquire file leases for a worker.
    * @param {string} workerId — worker/shard identifier
    * @param {string[]} files — file paths to lock
+   * @param {{ leaseType?: "exclusive" | "shared-read", sessionMeta?: { sessionId: string, host: string, taskSummary: string } }} [opts]
    * @returns {{ ok: boolean, acquired: string[], conflicts: Array<{ file: string, holder: string }> }}
    */
-  function acquire(workerId, files) {
+  function acquire(workerId, files, opts = {}) {
     pruneExpired();
 
+    const leaseType = normalizeLeaseType(opts.leaseType);
+    const sessionMeta = normalizeSessionMeta(opts.sessionMeta);
     const normalized = files.map((f) => normalizePath(f));
     const conflicts = [];
     const toAcquire = [];
+    const allowedSharedRead = [];
 
     for (let i = 0; i < normalized.length; i++) {
       const path = normalized[i];
       const existing = locks.get(path);
 
-      if (existing && existing.workerId !== workerId && !isExpired(existing)) {
+      if (!existing || isExpired(existing)) {
+        toAcquire.push(path);
+        continue;
+      }
+
+      if (hasConflict(existing, workerId, leaseType)) {
         conflicts.push({ file: files[i], holder: existing.workerId });
       } else {
-        toAcquire.push(path);
+        if (
+          !(
+            existing.workerId !== workerId &&
+            existing.leaseType === "shared-read" &&
+            leaseType === "shared-read"
+          )
+        ) {
+          toAcquire.push(path);
+        } else {
+          allowedSharedRead.push(path);
+        }
       }
     }
 
@@ -108,11 +180,15 @@ export function createSwarmLocks(opts = {}) {
 
     const ts = now();
     for (const path of toAcquire) {
-      locks.set(path, { workerId, acquiredAt: ts });
+      locks.set(path, { workerId, acquiredAt: ts, leaseType, sessionMeta });
     }
 
     persist();
-    return { ok: true, acquired: toAcquire, conflicts: [] };
+    return {
+      ok: true,
+      acquired: [...toAcquire, ...allowedSharedRead],
+      conflicts: [],
+    };
   }
 
   /**
@@ -136,35 +212,70 @@ export function createSwarmLocks(opts = {}) {
    * Check if a file write would violate any lease.
    * @param {string} workerId — the worker attempting the write
    * @param {string} filePath — the file being written
+   * @param {"exclusive" | "shared-read"} [leaseType="exclusive"] — requested lease type
    * @returns {{ allowed: boolean, holder?: string }}
    */
-  function check(workerId, filePath) {
+  function check(workerId, filePath, leaseType = "exclusive") {
     pruneExpired();
     const path = normalizePath(filePath);
     const entry = locks.get(path);
+    const normalizedLeaseType = normalizeLeaseType(leaseType);
 
     if (!entry || isExpired(entry)) return { allowed: true };
-    if (entry.workerId === workerId) return { allowed: true };
+    if (!hasConflict(entry, workerId, normalizedLeaseType))
+      return { allowed: true };
     return { allowed: false, holder: entry.workerId };
   }
 
   /**
    * Validate a set of changed files against the lease map.
    * Returns all violations found.
+   *
+   * Beyond the basic cross-lease check, when `options.ownLease` is supplied
+   * (the caller's known lease set), this also flags out-of-lease writes to
+   * distribution-critical paths — e.g. recovery-patch fallouts where a
+   * worker's recorded diff carries `+++ /dev/null` deletions of files like
+   * `.claude-plugin/marketplace.json` (regression of #115 / #34).
+   *
+   * `options.ownLease` is opt-in to preserve existing callers; when omitted,
+   * legacy behavior (cross-lease check only) is kept.
+   *
    * @param {string} workerId
    * @param {string[]} changedFiles
-   * @returns {Array<{ file: string, holder: string }>}
+   * @param {{ ownLease?: string[], sensitiveDeny?: { prefixes?: string[], files?: string[] } }} [options]
+   * @returns {Array<{ file: string, holder?: string, kind: "other-lease" | "sensitive-out-of-lease" }>}
    */
-  function validateChanges(workerId, changedFiles) {
+  function validateChanges(workerId, changedFiles, options = {}) {
     pruneExpired();
     const violations = [];
+    const ownLeaseSet = Array.isArray(options.ownLease)
+      ? new Set(options.ownLease.map((path) => normalizePath(path)))
+      : null;
+    const sensitivePrefixes =
+      options.sensitiveDeny?.prefixes ?? SENSITIVE_PATH_PREFIXES;
+    const sensitiveFiles = new Set(
+      options.sensitiveDeny?.files ?? SENSITIVE_PATH_FILES,
+    );
 
     for (const file of changedFiles) {
       const path = normalizePath(file);
       const entry = locks.get(path);
 
       if (entry && entry.workerId !== workerId && !isExpired(entry)) {
-        violations.push({ file, holder: entry.workerId });
+        violations.push({ file, holder: entry.workerId, kind: "other-lease" });
+        continue;
+      }
+
+      // Sensitive-path guard only runs when caller supplied ownLease.
+      // We only flag when the worker did NOT explicitly lease the file —
+      // an explicit lease means the shard intentionally owns it.
+      if (ownLeaseSet && !ownLeaseSet.has(path)) {
+        const isSensitive =
+          sensitiveFiles.has(path) ||
+          sensitivePrefixes.some((prefix) => path.startsWith(prefix));
+        if (isSensitive) {
+          violations.push({ file, kind: "sensitive-out-of-lease" });
+        }
       }
     }
 
@@ -173,7 +284,7 @@ export function createSwarmLocks(opts = {}) {
 
   /**
    * Get snapshot of all active locks.
-   * @returns {Array<{ file: string, workerId: string, acquiredAt: number }>}
+   * @returns {Array<{ file: string, workerId: string, acquiredAt: number, leaseType: "exclusive" | "shared-read", sessionMeta: { sessionId: string, host: string, taskSummary: string } | null }>}
    */
   function snapshot() {
     pruneExpired();
@@ -181,6 +292,8 @@ export function createSwarmLocks(opts = {}) {
       file,
       workerId: entry.workerId,
       acquiredAt: entry.acquiredAt,
+      leaseType: normalizeLeaseType(entry.leaseType),
+      sessionMeta: normalizeSessionMeta(entry.sessionMeta),
     }));
   }
 
@@ -199,6 +312,8 @@ export function createSwarmLocks(opts = {}) {
     validateChanges,
     snapshot,
     releaseAll,
-    get size() { return locks.size; },
+    get size() {
+      return locks.size;
+    },
   });
 }