@yemi33/minions 0.1.1960 → 0.1.1961

package/engine/lifecycle.js

@@ -2332,6 +2332,38 @@ function checkForLearnings(agentId, agentInfo, taskDesc) {
   log('info', `${agentInfo?.name || agentId} didn't write learnings — no follow-up queued`);
 }
 
+// E2.a (W-mp7goxe4000p75f7): name-normalised dedup against the personal-scope
+// skill dir. Strips a trailing `-[a-z0-9]{4,8}` random-suffix on the candidate
+// and re-checks against existing stems; also does simple prefix-match.
+// Returns the matched existing stem, or null if no near-duplicate.
+// Read-only — never deletes or renames existing skills.
+function _findNearDuplicateSkill(personalSkillRoot, candidateName) {
+  if (!personalSkillRoot || !candidateName) return null;
+  let entries;
+  try {
+    entries = fs.readdirSync(personalSkillRoot, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+  } catch { return null; }
+  if (entries.length === 0) return null;
+
+  // 1. Strip trailing `-[a-z0-9]{4,8}` random suffix and re-check.
+  const stripped = candidateName.replace(/-[a-z0-9]{4,8}$/, '');
+  if (stripped !== candidateName && entries.includes(stripped)) {
+    return stripped;
+  }
+
+  // 2. Prefix-match against existing stems. Either direction:
+  //    - candidate `foo-bar-x4y2` vs existing `foo-bar`
+  //    - candidate `foo` vs existing `foo-bar`
+  for (const existing of entries) {
+    if (existing === candidateName) continue;
+    if (candidateName.startsWith(existing + '-')) return existing;
+    if (existing.startsWith(candidateName + '-')) return existing;
+  }
+  return null;
+}
+
 function skillWriteTargets(runtimeName, project = null) {
   try {
     const runtime = resolveRuntime(runtimeName || 'claude');
@@ -2408,22 +2440,42 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config, runtimeN
       const personalSkillRoot = skillWriteTargets(effectiveRuntime).personal;
       const skillDir = path.join(personalSkillRoot, name.replace(/[^a-z0-9-]/g, '-'));
       const skillPath = path.join(skillDir, 'SKILL.md');
-      if (!fs.existsSync(skillPath)) {
-        // Native skill format: only name + description in frontmatter. The
-        // `Auto-extracted` marker is an HTML comment so the dashboard's
-        // autoGenerated detection picks it up without polluting the body
-        // an agent reads.
-        const description = m('description') || m('trigger') || `Auto-extracted skill from ${agentName}`;
-        const body = fmMatch[2] || '';
-        const marker = `<!-- Auto-extracted by ${agentName} on ${dateStamp()} -->`;
-        const ccContent = `---\nname: ${name}\ndescription: ${description}\n---\n\n${marker}\n\n${body.trim()}\n`;
-        if (!fs.existsSync(skillDir)) fs.mkdirSync(skillDir, { recursive: true });
-        shared.safeWrite(skillPath, ccContent);
-        try { require('./queries').invalidateSkillsCache(); } catch {}
-        log('info', `Extracted skill "${name}" from ${agentName} → ${skillPath}`);
-      } else {
+      if (fs.existsSync(skillPath)) {
         log('info', `Skill "${name}" already exists, skipping`);
+        continue;
+      }
+      // E2.a (W-mp7goxe4000p75f7): catch random-suffix and prefix-match
+      // near-duplicates BEFORE writing. Logs + flags for human review;
+      // no existing skills are deleted or renamed.
+      const nearDup = _findNearDuplicateSkill(personalSkillRoot, name.replace(/[^a-z0-9-]/g, '-'));
+      if (nearDup) {
+        log('warn', `Skill "${name}" appears to be a near-duplicate of "${nearDup}", skipping`);
+        const flaggedPath = path.join(ENGINE_DIR, 'skills-flagged.json');
+        mutateJsonFileLocked(flaggedPath, (data) => {
+          const arr = Array.isArray(data) ? data : [];
+          arr.push({
+            timestamp: ts(),
+            candidate: name,
+            existing: nearDup,
+            agent: agentName,
+            dispatchId: dispatchItem?.id || null,
+          });
+          return arr;
+        });
+        continue;
       }
+      // Native skill format: only name + description in frontmatter. The
+      // `Auto-extracted` marker is an HTML comment so the dashboard's
+      // autoGenerated detection picks it up without polluting the body
+      // an agent reads.
+      const description = m('description') || m('trigger') || `Auto-extracted skill from ${agentName}`;
+      const body = fmMatch[2] || '';
+      const marker = `<!-- Auto-extracted by ${agentName} on ${dateStamp()} -->`;
+      const ccContent = `---\nname: ${name}\ndescription: ${description}\n---\n\n${marker}\n\n${body.trim()}\n`;
+      if (!fs.existsSync(skillDir)) fs.mkdirSync(skillDir, { recursive: true });
+      shared.safeWrite(skillPath, ccContent);
+      try { require('./queries').invalidateSkillsCache(); } catch {}
+      log('info', `Extracted skill "${name}" from ${agentName} → ${skillPath}`);
 
     }
   }

package/engine/playbook.js

@@ -619,6 +619,54 @@ function buildSystemPrompt(agentId, config, project) {
   return prompt;
 }
 
+// E2.b (W-mp7goxe4000p75f7): build the `## Existing Skills (do not duplicate)`
+// section for buildAgentContext. Lists name + first-line description for every
+// personal-scope/installed-plugin skill discovered by queries.getSkills().
+// Caps at ~2KB by truncating alphabetically with a "_...and N more_" tail.
+// Returns '' when there are no personal-scope skills to advertise.
+const EXISTING_SKILLS_MAX_BYTES = 2048;
+const PERSONAL_SKILL_SCOPES = new Set(['claude-code', 'copilot', 'agent-skill', 'plugin', 'copilot-plugin']);
+
+function _buildExistingSkillsSection(config) {
+  let skills;
+  try {
+    skills = queries.getSkills(config) || [];
+  } catch { return ''; }
+  const personal = skills
+    .filter(s => PERSONAL_SKILL_SCOPES.has(s.scope))
+    .map(s => ({
+      name: String(s.name || '').trim(),
+      description: String(s.description || '').split('\n')[0].trim(),
+    }))
+    .filter(s => s.name)
+    .sort((a, b) => a.name.localeCompare(b.name));
+  if (personal.length === 0) return '';
+
+  const header = `## Existing Skills (do not duplicate)\n\nThese personal-scope skills already exist on disk. Do NOT emit a \`\`\`skill block whose name duplicates or near-duplicates one of these — the engine will flag it for human review and skip the write.\n\n`;
+  const lines = personal.map(s => s.description ? `- ${s.name} — ${s.description}` : `- ${s.name}`);
+
+  let body = lines.join('\n') + '\n\n';
+  if (Buffer.byteLength(header + body, 'utf8') <= EXISTING_SKILLS_MAX_BYTES) {
+    return header + body;
+  }
+
+  // Truncate alphabetically until we fit, leaving room for the tail line.
+  let kept = lines.length;
+  while (kept > 0) {
+    const dropped = lines.length - kept;
+    const tail = `_...and ${dropped} more (alphabetical truncation; full list on disk)_\n\n`;
+    body = lines.slice(0, kept).join('\n') + '\n' + tail;
+    if (Buffer.byteLength(header + body, 'utf8') <= EXISTING_SKILLS_MAX_BYTES) {
+      return header + body;
+    }
+    kept--;
+  }
+  // Pathological: header alone exceeds the cap. Return at least the header
+  // with a tail showing every skill was dropped, so the agent still sees the
+  // section heading.
+  return header + `_...and ${lines.length} more (alphabetical truncation; full list on disk)_\n\n`;
+}
+
 // Bulk context: history, notes, conventions, skills — prepended to user/task prompt.
 // This is the content that grows over time and would bloat the system prompt.
 function buildAgentContext(agentId, config, project) {
@@ -671,7 +719,12 @@ function buildAgentContext(agentId, config, project) {
 
   appendIndex('Knowledge Base Reference', getKnowledgeBaseIndex(), 8192);
 
-  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`, and project-local playbooks live in \`projects/<project>/playbooks/\`. Runtime-native skills and commands are left to the selected CLI runtime; Minions does not inject their contents into the task prompt.\n\n`;
+  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`, and project-local playbooks live in \`projects/<project>/playbooks/\`. Runtime-native skills and commands live in their native indexes (the catalog of names + descriptions is injected below as "Existing Skills"; full skill bodies are not).\n\n`;
+
+  // E2.b (W-mp7goxe4000p75f7): inject existing personal-scope skill catalog
+  // so agents can see what already exists before emitting a near-duplicate
+  // skill block. Caps at ~2KB; truncates alphabetically with a tail count.
+  context += _buildExistingSkillsSection(config);
 
   // Minions awareness: what's in flight, who's doing what
   const dispatch = getDispatch();

package/engine/worktree-pool.js

@@ -148,85 +148,6 @@ function tryBorrow(projectName, dispatchId, opts) {
   return borrowed;
 }
 
-/**
- * Register a brand-new worktree as a borrowed pool member. Used when a fresh
- * worktree is created (no idle slot available) and the pool has room — we
- * track it from creation so the eventual return is a simple state flip.
- *
- * Honors capacity inside the locked mutation: if the project is already at or
- * over `poolSize`, the registration is rejected and the worktree stays
- * untracked (cleanup will reap it normally).
- */
-function registerBorrowed(projectName, wtPath, dispatchId, opts) {
-  opts = opts || {};
-  if (!projectName || !wtPath || !dispatchId) return false;
-  const poolSize = Number.isFinite(opts.poolSize) ? Math.max(0, Math.floor(opts.poolSize)) : 0;
-  if (poolSize <= 0) return false;
-  const branch = opts.branch || '';
-  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
-  let registered = false;
-  mutateWorktreePool((data) => {
-    const entries = data.entries;
-    // Already tracked? Update the borrower fields and keep going.
-    const existingIdx = _findEntryByPath(entries, wtPath);
-    if (existingIdx !== -1) {
-      const e = entries[existingIdx];
-      e.state = POOL_STATE.BORROWED;
-      e.borrowedBy = dispatchId;
-      e.borrowedAt = _nowIso(now);
-      e.idleSince = null;
-      if (branch) e.lastBranch = branch;
-      e.lastUsed = e.borrowedAt;
-      registered = true;
-      return data;
-    }
-    // Capacity gate — count entries (idle + borrowed) for this project.
-    const projectCount = entries.filter(e => e && e.project === projectName).length;
-    if (projectCount >= poolSize) return data;
-    entries.push({
-      project: projectName,
-      path: wtPath,
-      state: POOL_STATE.BORROWED,
-      borrowedBy: dispatchId,
-      borrowedAt: _nowIso(now),
-      idleSince: null,
-      lastBranch: branch,
-      createdAt: _nowIso(now),
-      lastUsed: _nowIso(now),
-    });
-    registered = true;
-    return data;
-  });
-  return registered;
-}
-
-/**
- * Mark a borrowed entry as idle. Caller is responsible for having already run
- * the git reset/clean/checkout-detach/pull dance — this is purely a state
- * flip. If the entry is unknown, no-op (caller can decide to register first).
- */
-function markIdle(wtPath, opts) {
-  opts = opts || {};
-  if (!wtPath) return false;
-  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
-  const branch = opts.branch || '';
-  let flipped = false;
-  mutateWorktreePool((data) => {
-    const idx = _findEntryByPath(data.entries, wtPath);
-    if (idx === -1) return data;
-    const e = data.entries[idx];
-    e.state = POOL_STATE.IDLE;
-    e.borrowedBy = null;
-    e.borrowedAt = null;
-    e.idleSince = _nowIso(now);
-    e.lastUsed = _nowIso(now);
-    if (branch) e.lastBranch = branch;
-    flipped = true;
-    return data;
-  });
-  return flipped;
-}
-
 /**
  * Return a worktree to the pool — flip an existing borrowed entry to idle, or
  * insert a fresh entry as idle when the project is under capacity. Both paths
@@ -353,8 +274,8 @@ function pruneStale(opts) {
 }
 
 /**
- * Count entries (idle + borrowed) belonging to a project. Used to gate
- * `markIdle` registrations from fresh-create paths.
+ * Count entries (idle + borrowed) belonging to a project. Used for capacity
+ * gating diagnostics and pool-size dashboards.
  */
 function countForProject(projectName) {
   if (!projectName) return 0;
@@ -397,8 +318,6 @@ module.exports = {
   isPoolMember,
   getEntry,
   tryBorrow,
-  registerBorrowed,
-  markIdle,
   returnToPool,
   evictEntry,
   pruneStale,

package/engine.js

@@ -990,8 +990,15 @@ async function spawnAgent(dispatchItem, config) {
           if (borrowed && borrowed.path && fs.existsSync(borrowed.path)) {
             try { shared.assertWorktreeOutsideProject(borrowed.path, rootDir); }
             catch (assertErr) {
+              // Always evict before deciding what to do — leaves no BORROWED
+              // orphan tied to a dispatch that won't complete normally.
+              // pruneStale would self-heal in ~10 ticks via orphan-borrow, but
+              // that window is unnecessary.
+              const _evictReason = assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT'
+                ? 'nested-in-project'
+                : 'assert-failed';
+              worktreePool.evictEntry(borrowed.path, _evictReason);
               if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') {
-                worktreePool.evictEntry(borrowed.path, 'nested-in-project');
                 _failWorktreePreflight(assertErr); return null;
               }
               throw assertErr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1960",
+  "version": "0.1.1961",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"