@claude-flow/cli 3.32.34 → 3.32.36

package/dist/src/mcp-tools/hooks-tools.js

@@ -8,6 +8,7 @@ import { dirname, join, resolve } from 'path';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText, validatePath } from './validate-input.js';
 import { checkCommandLoop, recordCommandOutcome } from './tool-loop-guardrail.js';
+import { buildLearnedRoutingPatterns, } from '../services/learned-routing.js';
 // Real vector search functions - lazy loaded to avoid circular imports
 let searchEntriesFn = null;
 /**
@@ -185,6 +186,13 @@ function saveRoutingOutcomes(outcomes) {
         // Cap at 500 entries to bound file size
         const capped = outcomes.slice(-500);
         writeFileSync(ROUTING_OUTCOMES_PATH, JSON.stringify({ outcomes: capped }, null, 2));
+        // A long-lived MCP process must observe the new label on the next route.
+        // The prior singleton cache made the learned store inert until restart.
+        semanticRouter = null;
+        nativeVectorDb = null;
+        semanticRouterInitialized = false;
+        routerBackend = 'none';
+        TASK_PATTERN_EMBEDDINGS.clear();
     }
     catch { /* non-critical */ }
 }
@@ -194,24 +202,7 @@ function saveRoutingOutcomes(outcomes) {
  * merged into both the native HNSW and pure-JS semantic routers.
  */
 function loadLearnedPatterns() {
-    const outcomes = loadRoutingOutcomes();
-    const byAgent = {};
-    for (const o of outcomes) {
-        if (!o.success || !o.agent || !o.keywords?.length)
-            continue;
-        if (!byAgent[o.agent])
-            byAgent[o.agent] = new Set();
-        for (const kw of o.keywords)
-            byAgent[o.agent].add(kw);
-    }
-    const patterns = {};
-    for (const [agent, kwSet] of Object.entries(byAgent)) {
-        patterns[`learned-${agent}`] = {
-            keywords: [...kwSet].slice(0, 50),
-            agents: [agent],
-        };
-    }
-    return patterns;
+    return buildLearnedRoutingPatterns(loadRoutingOutcomes());
 }
 /**
  * Merge static TASK_PATTERNS with runtime-learned patterns.
@@ -290,46 +281,55 @@ async function getSemanticRouter() {
     // STEP 1: Try native VectorDb from @ruvector/router (HNSW-backed)
     // Note: Native VectorDb uses a persistent database file which can have lock issues
     // in concurrent environments. We try it first but fall back gracefully to pure JS.
-    try {
-        // Use createRequire for ESM compatibility with native modules
-        const { createRequire } = await import('module');
-        const require = createRequire(import.meta.url);
-        const router = require('@ruvector/router');
-        if (router.VectorDb && router.DistanceMetric) {
-            // Try to create VectorDb - may fail with lock error in concurrent envs
-            const db = new router.VectorDb({
-                dimensions: 384,
-                distanceMetric: router.DistanceMetric.Cosine,
-                hnswM: 16,
-                hnswEfConstruction: 200,
-                hnswEfSearch: 100,
-            });
-            // Initialize with static + runtime-learned task patterns
-            for (const [patternName, { keywords }] of Object.entries(getMergedTaskPatterns())) {
-                for (const keyword of keywords) {
-                    const embedding = generateSimpleEmbedding(keyword);
-                    db.insert(`${patternName}:${keyword}`, embedding);
-                    TASK_PATTERN_EMBEDDINGS.set(`${patternName}:${keyword}`, embedding);
+    // Deterministic/test and lock-constrained environments may force the
+    // pure-JS router; production continues to prefer the native backend.
+    if (process.env.CLAUDE_FLOW_DISABLE_NATIVE_ROUTER !== '1')
+        try {
+            // Use createRequire for ESM compatibility with native modules
+            const { createRequire } = await import('module');
+            const require = createRequire(import.meta.url);
+            const router = require('@ruvector/router');
+            if (router.VectorDb && router.DistanceMetric) {
+                // Try to create VectorDb - may fail with lock error in concurrent envs
+                const db = new router.VectorDb({
+                    dimensions: 384,
+                    distanceMetric: router.DistanceMetric.Cosine,
+                    hnswM: 16,
+                    hnswEfConstruction: 200,
+                    hnswEfSearch: 100,
+                });
+                // Initialize with static + runtime-learned task patterns
+                for (const [patternName, { keywords }] of Object.entries(getMergedTaskPatterns())) {
+                    for (const keyword of keywords) {
+                        const embedding = generateSimpleEmbedding(keyword);
+                        db.insert(`${patternName}:${keyword}`, embedding);
+                        TASK_PATTERN_EMBEDDINGS.set(`${patternName}:${keyword}`, embedding);
+                    }
                 }
+                nativeVectorDb = db;
+                routerBackend = 'native';
+                console.log('[hooks] Semantic router initialized: native VectorDb (HNSW, 16k+ routes/s)');
+                return { router: null, backend: routerBackend, native: nativeVectorDb };
             }
-            nativeVectorDb = db;
-            routerBackend = 'native';
-            console.log('[hooks] Semantic router initialized: native VectorDb (HNSW, 16k+ routes/s)');
-            return { router: null, backend: routerBackend, native: nativeVectorDb };
         }
-    }
-    catch (err) {
-        // Native not available or database locked - fall back to pure JS
-        // Common errors: "Database already open. Cannot acquire lock." or "MODULE_NOT_FOUND"
-        // This is expected in concurrent environments or when binary isn't installed
-    }
+        catch (err) {
+            // Native not available or database locked - fall back to pure JS
+            // Common errors: "Database already open. Cannot acquire lock." or "MODULE_NOT_FOUND"
+            // This is expected in concurrent environments or when binary isn't installed
+        }
     // STEP 2: Fall back to pure JS SemanticRouter
     try {
         const { SemanticRouter } = await import('../ruvector/semantic-router.js');
         semanticRouter = new SemanticRouter({ dimension: 384 });
-        for (const [patternName, { keywords, agents }] of Object.entries(getMergedTaskPatterns())) {
+        for (const [patternName, { keywords, agents, source, support, reliability }] of Object.entries(getMergedTaskPatterns())) {
             const embeddings = keywords.map(kw => generateSimpleEmbedding(kw));
-            semanticRouter.addIntentWithEmbeddings(patternName, embeddings, { agents, keywords });
+            semanticRouter.addIntentWithEmbeddings(patternName, embeddings, {
+                agents,
+                keywords,
+                source: source ?? 'static',
+                support,
+                reliability,
+            });
             // Cache embeddings for keywords
             keywords.forEach((kw, i) => {
                 TASK_PATTERN_EMBEDDINGS.set(kw, embeddings[i]);
@@ -439,6 +439,20 @@ function getIntelligenceStatsFromMemory() {
         const category = e.metadata?.category || 'general';
         categories[category] = (categories[category] || 0) + 1;
     });
+    const successfulPatterns = patternEntries.filter(e => e.metadata?.success === true).length;
+    const failedPatterns = patternEntries.filter(e => e.metadata?.success === false).length;
+    const describedPatterns = patternEntries.filter(e => {
+        if (typeof e.metadata?.task === 'string' && e.metadata.task.trim())
+            return true;
+        try {
+            const value = typeof e.value === 'string' ? JSON.parse(e.value) : e.value;
+            return typeof value?.task === 'string' &&
+                Boolean(String(value.task).trim());
+        }
+        catch {
+            return false;
+        }
+    }).length;
     // Count routing decisions
     const routingEntries = entries.filter(e => e.key.includes('routing') ||
         e.metadata?.type === 'routing-decision');
@@ -472,6 +486,10 @@ function getIntelligenceStatsFromMemory() {
         },
         patterns: {
             learned: patternEntries.length,
+            successful: successfulPatterns,
+            failed: failedPatterns,
+            unknown: Math.max(0, patternEntries.length - successfulPatterns - failedPatterns),
+            described: describedPatterns,
             categories,
         },
         memory: {
@@ -946,6 +964,9 @@ export const hooksRoute = {
                         score: 1 - r.score, // Native uses distance (lower is better), convert to similarity
                         metadata: {
                             agents: pattern?.agents || (patternName.startsWith('learned-') ? [patternName.slice(8)] : ['coder']),
+                            source: pattern?.source ?? (patternName.startsWith('learned-') ? 'learned' : 'static'),
+                            support: pattern?.support,
+                            reliability: pattern?.reliability,
                         },
                     };
                 });
@@ -966,8 +987,18 @@ export const hooksRoute = {
         let agents;
         let confidence;
         let matchedPattern = '';
-        if (semanticResult.length > 0 && semanticResult[0].score > 0.4) {
-            const topMatch = semanticResult[0];
+        const eligibleSemantic = semanticResult.find((match) => {
+            if (match.score <= 0.4)
+                return false;
+            const learned = match.intent.startsWith('learned-') || match.metadata.source === 'learned';
+            if (!learned)
+                return true;
+            return match.score >= 0.65
+                && Number(match.metadata.support ?? 0) >= 2
+                && Number(match.metadata.reliability ?? 0) >= 0.75;
+        });
+        if (eligibleSemantic) {
+            const topMatch = eligibleSemantic;
             agents = topMatch.metadata.agents || ['coder', 'researcher'];
             confidence = topMatch.score;
             matchedPattern = topMatch.intent;
@@ -1061,21 +1092,28 @@ export const hooksMetrics = {
                 agentCounts[o.agent] = (agentCounts[o.agent] || 0) + 1;
         }
         const topAgent = Object.entries(agentCounts).sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
-        const successful = stats.trajectories.successful;
-        const total = stats.trajectories.total;
-        const failed = Math.max(0, total - successful);
         return {
             _real: true,
             _dataSource: 'intelligence-stats + routing-outcomes',
             period,
             patterns: {
                 total: stats.patterns.learned,
-                successful,
-                failed,
+                successful: stats.patterns.successful,
+                failed: stats.patterns.failed,
+                unknown: stats.patterns.unknown,
+                described: stats.patterns.described,
+                descriptionCoverage: stats.patterns.learned > 0
+                    ? stats.patterns.described / stats.patterns.learned
+                    : null,
                 avgConfidence: stats.routing.avgConfidence || null,
             },
             agents: {
-                routingAccuracy: stats.routing.avgConfidence || null,
+                // Confidence is a model self-score, not observed routing accuracy
+                // (#2809). Keep the old key as an explicit null for compatibility
+                // while exposing the truthful additive field.
+                routingAccuracy: null,
+                averageConfidence: stats.routing.avgConfidence || null,
+                outcomeSuccessRate: successRate,
                 totalRoutes: stats.routing.decisions,
                 topAgent,
             },
@@ -1084,7 +1122,7 @@ export const hooksMetrics = {
                 successRate,
                 avgRiskScore: null,
             },
-            _note: total === 0 && totalCommands === 0
+            _note: stats.patterns.learned === 0 && totalCommands === 0
                 ? 'No metrics data collected yet. Run hooks_post-task / hooks_intelligence_trajectory-end / hooks_route to populate.'
                 : undefined,
             lastUpdated: new Date().toISOString(),
@@ -1249,6 +1287,10 @@ export const hooksPostTask = {
             agent: { type: 'string', description: 'Agent that completed the task' },
             quality: { type: 'number', description: 'Quality score (0-1)' },
             task: { type: 'string', description: 'Task description text (used for learning keyword extraction)' },
+            duration: { type: 'number', description: 'Observed task duration in milliseconds (used by pheromone-adaptive topology)' },
+            latencyBudgetMs: { type: 'number', description: 'Latency budget used to normalize duration (default 60000ms)' },
+            consensusAlignment: { type: 'number', description: 'Agreement with accepted swarm consensus in [0,1] (default quality)' },
+            agentRole: { type: 'string', description: 'Role for role-local pheromone normalization (default agent)' },
             storeDecisions: { type: 'boolean', description: 'Also store routing decision in memory DB' },
             // ADR-147 P2: nested-subagent spawn-tree capture
             parentAgentId: { type: 'string', description: 'ID of the parent agent (from Claude Code\'s parent_agent_id OTel span tag / x-claude-code-parent-agent-id header). Omit for top-level work.' },
@@ -1294,6 +1336,7 @@ export const hooksPostTask = {
             const bridge = await import('../memory/memory-bridge.js');
             feedbackResult = await bridge.bridgeRecordFeedback({
                 taskId,
+                task: params.task || undefined,
                 success,
                 quality,
                 agent,
@@ -1405,6 +1448,22 @@ export const hooksPostTask = {
             }
             catch { /* non-critical */ }
         }
+        let pheromone;
+        if (agent) {
+            try {
+                const { recordSwarmPheromoneSignal } = await import('./swarm-tools.js');
+                const observedDuration = Math.max(0, Number(params.duration ?? (Date.now() - startTime)));
+                const latencyBudgetMs = Math.max(1, Number(params.latencyBudgetMs ?? 60_000));
+                pheromone = recordSwarmPheromoneSignal({
+                    agentId: agent,
+                    role: String(params.agentRole ?? agent),
+                    taskSuccess: success ? 1 : 0,
+                    normalizedLatency: Math.max(0, Math.min(1, observedDuration / latencyBudgetMs)),
+                    consensusAlignment: Math.max(0, Math.min(1, Number(params.consensusAlignment ?? quality))),
+                });
+            }
+            catch { /* no active APSC swarm or optional path unavailable */ }
+        }
         const duration = Date.now() - startTime;
         // Persist to auto-memory-store for statusline visibility
         try {
@@ -1444,6 +1503,7 @@ export const hooksPostTask = {
                 outcomePersisted,
             },
             quality,
+            pheromone,
             feedback: feedbackResult ? {
                 recorded: feedbackResult.success,
                 controller: feedbackResult.controller,
@@ -3102,7 +3162,7 @@ export const hooksIntelligenceStats = {
         catch {
             memoryStats = {
                 trajectories: { total: 0, successful: 0 },
-                patterns: { learned: 0, categories: {} },
+                patterns: { learned: 0, successful: 0, failed: 0, unknown: 0, described: 0, categories: {} },
                 memory: { indexSize: 0, totalAccessCount: 0, memorySizeBytes: 0 },
                 routing: { decisions: 0, avgConfidence: 0 },
             };

package/dist/src/mcp-tools/memory-tools.js

@@ -1175,6 +1175,7 @@ export const memoryTools = [
         handler: async (input) => {
             await ensureInitialized();
             const { listEntries, deleteEntry } = await getMemoryFunctions();
+            const startedAt = Date.now();
             const dryRun = input.dryRun !== false; // default true
             const namespace = input.namespace ? String(input.namespace) : undefined;
             if (namespace) {
@@ -1193,6 +1194,7 @@ export const memoryTools = [
             });
             let freedBytes = 0;
             let deleted = 0;
+            let vectorsRemoved = 0;
             if (!dryRun) {
                 for (const e of expired) {
                     try {
@@ -1206,11 +1208,21 @@ export const memoryTools = [
             else {
                 freedBytes = expired.reduce((s, e) => s + (e.size || 0), 0);
             }
+            if (!dryRun) {
+                const { reconcileHNSWIndex } = await import('../memory/memory-initializer.js');
+                vectorsRemoved = await reconcileHNSWIndex();
+            }
+            const formatted = freedBytes < 1024
+                ? `${freedBytes} B`
+                : freedBytes < 1024 * 1024
+                    ? `${(freedBytes / 1024).toFixed(1)} KiB`
+                    : `${(freedBytes / (1024 * 1024)).toFixed(1)} MiB`;
             return {
                 dryRun,
                 candidates: { expired: expired.length, stale: 0, lowQuality: 0, total: expired.length },
-                deleted: { entries: dryRun ? 0 : deleted, vectors: 0, patterns: 0 },
-                freed: { bytes: freedBytes },
+                deleted: { entries: dryRun ? 0 : deleted, vectors: vectorsRemoved, patterns: 0 },
+                freed: { bytes: freedBytes, formatted },
+                duration: Date.now() - startedAt,
                 note: dryRun ? 'dry run — re-run with dryRun:false to delete' : undefined,
             };
         },

package/dist/src/mcp-tools/metaharness-tools.js

@@ -700,6 +700,9 @@ export const metaharnessTools = [
                 confirm: { type: 'boolean', description: 'Required for promote; never inferred', default: false },
                 maxConcurrency: { type: 'number', description: 'ADR-324 hard local candidate-evaluation concurrency cap (1-8)', default: 2 },
                 timeoutMs: { type: 'number', description: 'Abort concurrent evaluation after this wall-clock limit', default: 120000 },
+                anchorPath: { type: 'string', description: 'Project-contained human-labelled anchor JSON; requires anchorHash' },
+                anchorHash: { type: 'string', description: 'Pinned sha256 of canonical anchor tasks; requires anchorPath' },
+                anchorManifestPath: { type: 'string', description: 'Project-contained anchor manifest path (default .claude/eval/flywheel-anchor.manifest.json)' },
                 approvalIds: { type: 'array', items: { type: 'string' }, description: 'Scoped ADR-324 approval IDs for privileged promotion' },
             },
             required: ['operation'],
@@ -721,6 +724,7 @@ export const metaharnessTools = [
             if (operation === 'receipts') {
                 const data = listFlywheelReceipts(projectRoot).map(({ receipt, state }) => ({
                     receiptId: receipt.payload.receiptId,
+                    anchorRef: receipt.payload.anchorRef,
                     candidateId: receipt.payload.candidateId,
                     baselineRef: receipt.payload.baselineRef,
                     decision: receipt.payload.decision,
@@ -748,6 +752,9 @@ export const metaharnessTools = [
                     receiptPublicKeyPem: publicKeyPath ? readFileSync(publicKeyPath, 'utf8') : undefined,
                     maxConcurrency: Number(input.maxConcurrency ?? 2),
                     evaluationTimeoutMs: Number(input.timeoutMs ?? 120_000),
+                    anchorPath: input.anchorPath ? String(input.anchorPath) : undefined,
+                    anchorHash: input.anchorHash ? String(input.anchorHash) : undefined,
+                    anchorManifestPath: input.anchorManifestPath ? String(input.anchorManifestPath) : undefined,
                 });
                 return { success: data.ran, data, degraded: false, exitCode: data.ran ? 0 : 1 };
             }

package/dist/src/mcp-tools/swarm-tools.d.ts

@@ -5,6 +5,7 @@
  * Replaces previous stub implementations with real state tracking.
  */
 import { type MCPTool } from './types.js';
+import { type ApscDecision, type ApscSignal } from '../services/pheromone-adaptive.js';
 interface SwarmState {
     swarmId: string;
     topology: string;
@@ -32,6 +33,21 @@ interface SwarmStore {
 }
 export declare function loadSwarmStore(): SwarmStore;
 export declare function saveSwarmStore(store: SwarmStore): void;
+/** Shared by hooks_post-task so outcome labels immediately drive APSC. */
+export declare function recordSwarmPheromoneSignal(signal: ApscSignal): {
+    active: false;
+    reason: string;
+} | {
+    active: true;
+    swarmId: string;
+    decision: ApscDecision;
+};
+/** Scheduling gate used by agent_execute. Dry-run topologies remain eligible. */
+export declare function pheromoneAgentEligibility(agentId: string): {
+    eligible: boolean;
+    active: boolean;
+    reason?: string;
+};
 export declare const swarmTools: MCPTool[];
 export {};
 //# sourceMappingURL=swarm-tools.d.ts.map

package/dist/src/mcp-tools/swarm-tools.js

@@ -4,13 +4,16 @@
  * Tool definitions for swarm coordination with file-based state persistence.
  * Replaces previous stub implementations with real state tracking.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier } from './validate-input.js';
+import { createApscState, isApscAgentEligible, normalizeApscConfig, recordApscSignal, } from '../services/pheromone-adaptive.js';
 // Swarm state persistence
 const SWARM_DIR = '.claude-flow/swarm';
 const SWARM_STATE_FILE = 'swarm-state.json';
+const SWARM_STATE_LOCK = 'swarm-state.lock';
+const SWARM_LOCK_STALE_MS = 10_000;
 function getSwarmDir() {
     return join(getProjectCwd(), SWARM_DIR);
 }
@@ -103,12 +106,101 @@ export function loadSwarmStore() {
 }
 export function saveSwarmStore(store) {
     ensureSwarmDir();
-    writeFileSync(getSwarmStatePath(), JSON.stringify(store, null, 2), 'utf-8');
+    const target = getSwarmStatePath();
+    const temporary = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        writeFileSync(temporary, JSON.stringify(store, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        renameSync(temporary, target);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch { /* already renamed or never created */ }
+        throw error;
+    }
+}
+function withSwarmStoreLock(operation) {
+    ensureSwarmDir();
+    const lockPath = join(getSwarmDir(), SWARM_STATE_LOCK);
+    let descriptor;
+    const waiter = new Int32Array(new SharedArrayBuffer(4));
+    for (let attempt = 0; attempt < 100; attempt++) {
+        try {
+            descriptor = openSync(lockPath, 'wx', 0o600);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > SWARM_LOCK_STALE_MS) {
+                    unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch { /* another writer released it */ }
+            Atomics.wait(waiter, 0, 0, 10);
+        }
+    }
+    if (descriptor === undefined)
+        throw new Error('swarm state is busy; retry the outcome update');
+    try {
+        return operation();
+    }
+    finally {
+        try {
+            closeSync(descriptor);
+        }
+        catch { /* best effort */ }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* best effort */ }
+    }
 }
 // Input validation
 const VALID_TOPOLOGIES = new Set([
-    'hierarchical', 'mesh', 'hierarchical-mesh', 'ring', 'star', 'hybrid', 'adaptive',
+    'hierarchical', 'mesh', 'hierarchical-mesh', 'ring', 'star', 'hybrid', 'adaptive', 'pheromone-adaptive',
 ]);
+function latestRunningSwarm(store) {
+    return Object.values(store.swarms)
+        .filter((swarm) => swarm.status === 'running')
+        .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())[0];
+}
+function apscStateOf(swarm) {
+    if (!swarm || swarm.topology !== 'pheromone-adaptive')
+        return undefined;
+    const state = swarm.config.apscState;
+    return state?.schemaVersion ? state : undefined;
+}
+/** Shared by hooks_post-task so outcome labels immediately drive APSC. */
+export function recordSwarmPheromoneSignal(signal) {
+    return withSwarmStoreLock(() => {
+        const store = loadSwarmStore();
+        const swarm = latestRunningSwarm(store);
+        const current = apscStateOf(swarm);
+        if (!swarm || !current)
+            return { active: false, reason: 'no running pheromone-adaptive swarm' };
+        const result = recordApscSignal(current, signal);
+        swarm.config.apscState = result.state;
+        swarm.updatedAt = new Date().toISOString();
+        saveSwarmStore(store);
+        return { active: true, swarmId: swarm.swarmId, decision: result.decision };
+    });
+}
+/** Scheduling gate used by agent_execute. Dry-run topologies remain eligible. */
+export function pheromoneAgentEligibility(agentId) {
+    const current = apscStateOf(latestRunningSwarm(loadSwarmStore()));
+    if (!current)
+        return { eligible: true, active: false };
+    const eligible = isApscAgentEligible(current, agentId);
+    return {
+        eligible,
+        active: true,
+        reason: eligible ? undefined : 'agent suspended by pheromone-adaptive scheduling gate',
+    };
+}
 export const swarmTools = [
     {
         name: 'swarm_init',
@@ -117,7 +209,7 @@ export const swarmTools = [
         inputSchema: {
             type: 'object',
             properties: {
-                topology: { type: 'string', description: 'Swarm topology type (hierarchical, mesh, hierarchical-mesh, ring, star, hybrid, adaptive)' },
+                topology: { type: 'string', description: 'Swarm topology type (hierarchical, mesh, hierarchical-mesh, ring, star, hybrid, adaptive, pheromone-adaptive)' },
                 maxAgents: { type: 'number', description: 'Maximum number of agents (1-50)' },
                 strategy: { type: 'string', description: 'Agent strategy (specialized, balanced, adaptive)' },
                 config: { type: 'object', description: 'Additional swarm configuration' },
@@ -145,6 +237,19 @@ export const swarmTools = [
                     error: `Invalid topology: ${topology}. Valid: ${[...VALID_TOPOLOGIES].join(', ')}`,
                 };
             }
+            let apscState;
+            if (topology === 'pheromone-adaptive') {
+                try {
+                    const apscConfig = normalizeApscConfig((config.apsc ?? {}));
+                    if (apscConfig.minActiveAgents > maxAgents) {
+                        return { success: false, error: 'APSC minActiveAgents cannot exceed maxAgents' };
+                    }
+                    apscState = createApscState(apscConfig);
+                }
+                catch (error) {
+                    return { success: false, error: `Invalid APSC config: ${error.message}` };
+                }
+            }
             const swarmId = `swarm-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
             const now = new Date().toISOString();
             const swarmState = {
@@ -161,12 +266,14 @@ export const swarmTools = [
                     communicationProtocol: config.communicationProtocol || 'message-bus',
                     autoScaling: config.autoScaling ?? true,
                     consensusMechanism: config.consensusMechanism || 'majority',
+                    ...(apscState ? { apscState } : {}),
                 },
                 createdAt: now,
                 updatedAt: now,
-                // #1799 — record host PID so subsequent loads can detect orphans
-                // when this process exits without a graceful swarm_shutdown.
-                pid: process.pid,
+                // A normal CLI invocation exits immediately after creating this
+                // coordination record; its PID is therefore not the swarm lifetime.
+                // Long-lived hosts may opt into PID ownership explicitly.
+                pid: config.trackHostProcess === true ? process.pid : undefined,
             };
             const store = loadSwarmStore();
             store.swarms[swarmId] = swarmState;
@@ -180,6 +287,62 @@ export const swarmTools = [
                 initializedAt: now,
                 config: swarmState.config,
                 persisted: true,
+                apsc: apscState ? {
+                    dryRun: apscState.config.dryRun,
+                    minActiveAgents: apscState.config.minActiveAgents,
+                    minSamples: apscState.config.minSamples,
+                } : undefined,
+            };
+        },
+    },
+    {
+        name: 'swarm_pheromone_update',
+        description: 'Record a normalized per-agent task outcome for a running pheromone-adaptive swarm. Use when a static agent pool is wrong because repeated task evidence should update role-aware EMA fitness and produce a bounded keep/suspend/reactivate decision; native Task has no persistent swarm eligibility gate.',
+        category: 'swarm',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'Stable tracked agent identifier' },
+                role: { type: 'string', description: 'Agent role used for role-local normalization' },
+                taskSuccess: { type: 'number', description: 'Observed task success in [0,1]' },
+                normalizedLatency: { type: 'number', description: 'Latency divided by the configured budget, clamped to [0,1]' },
+                consensusAlignment: { type: 'number', description: 'Agreement with the accepted consensus in [0,1]' },
+            },
+            required: ['agentId', 'role', 'taskSuccess', 'normalizedLatency', 'consensusAlignment'],
+        },
+        handler: async (input) => {
+            try {
+                return recordSwarmPheromoneSignal({
+                    agentId: String(input.agentId),
+                    role: String(input.role),
+                    taskSuccess: Number(input.taskSuccess),
+                    normalizedLatency: Number(input.normalizedLatency),
+                    consensusAlignment: Number(input.consensusAlignment),
+                });
+            }
+            catch (error) {
+                return { active: false, reason: error.message };
+            }
+        },
+    },
+    {
+        name: 'swarm_pheromone_status',
+        description: 'Inspect the threshold, safety configuration, per-agent EMA scores, and scheduling eligibility of the active pheromone-adaptive swarm. Use when aggregate swarm status is wrong because calibration requires the exact APSC threshold and per-agent evidence before switching from dry-run to live suspension.',
+        category: 'swarm',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            const store = loadSwarmStore();
+            const swarm = latestRunningSwarm(store);
+            const state = apscStateOf(swarm);
+            if (!swarm || !state)
+                return { active: false, reason: 'no running pheromone-adaptive swarm' };
+            return {
+                active: true,
+                swarmId: swarm.swarmId,
+                threshold: state.threshold,
+                round: state.round,
+                config: state.config,
+                agents: Object.values(state.agents).sort((a, b) => a.agentId.localeCompare(b.agentId)),
             };
         },
     },
@@ -212,6 +375,7 @@ export const swarmTools = [
                     agentCount: swarm.agents.length,
                     taskCount: swarm.tasks.length,
                     config: swarm.config,
+                    apsc: apscStateOf(swarm),
                     createdAt: swarm.createdAt,
                     updatedAt: swarm.updatedAt,
                 };
@@ -236,6 +400,7 @@ export const swarmTools = [
                 agentCount: latest.agents.length,
                 taskCount: latest.tasks.length,
                 config: latest.config,
+                apsc: apscStateOf(latest),
                 createdAt: latest.createdAt,
                 updatedAt: latest.updatedAt,
                 totalSwarms: swarmIds.length,

package/dist/src/memory/memory-bridge.d.ts

@@ -322,6 +322,8 @@ export declare function bridgeSearchPatterns(options: {
  */
 export declare function bridgeRecordFeedback(options: {
     taskId: string;
+    /** Human-readable task text used as the semantic learning signal. */
+    task?: string;
     success: boolean;
     quality: number;
     agent?: string;